@polyester/sdk 0.27.1 → 0.27.2

package/dist/shared/catalog-config.d.ts

@@ -10,6 +10,8 @@ interface AssetConfig {
   name: string;
   quantityDisplayDecimals: number;
   quantityScale: number;
+  /** Scale for public candle and market-overview base volume. Absent on older snapshots. */
+  marketDataVolumeScale?: number;
 }
 interface PairConfig {
   symbolId: number;
@@ -27,6 +29,8 @@ interface PairConfig {
   marketdata?: PairMarketDataConfig;
   baseQuantityScale: number;
   quoteQuantityScale: number;
+  /** Scale for composite reference candle prices. Absent on older snapshots. */
+  referencePriceScale?: number;
   listingAt?: number | null;
   delistingAt?: number | null;
   status: PairStatus;

package/dist/shared/catalog-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog-config.d.ts","names":[],"sources":["../../src/shared/catalog-config.ts"],"mappings":";KAAY;EACR;;KAGQ;cAQC;UAQI;EACb;EACA;EACA;EACA;EACA;;UAGa;EACb;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,aAAa;EACb;EACA;EACA;EACA;EACA,QAAQ;;UAGK;EACb,QAAQ;EACR,OAAO;EACP;;UAGa;EACb;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;UAGa;EACb;EACA;;UAGa;EACb;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,aAAa;EACb,QAAQ;;UAGK;EACb;EACA;EACA;EACA;EACA;EACA;EACA,UAAU;EACV;;UAGa;EACb;EACA;EACA;EACA;EACA;;UAGa;EACb,QAAQ;EACR,QAAQ;EACR,WAAW;EACX"}
+{"version":3,"file":"catalog-config.d.ts","names":[],"sources":["../../src/shared/catalog-config.ts"],"mappings":";KAAY;EACR;;KAGQ;cAQC;UAQI;EACb;EACA;EACA;EACA;EACA;;EAEA;;UAGa;EACb;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,aAAa;EACb;EACA;;EAEA;EACA;EACA;EACA,QAAQ;;UAGK;EACb,QAAQ;EACR,OAAO;EACP;;UAGa;EACb;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;UAGa;EACb;EACA;;UAGa;EACb;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,aAAa;EACb,QAAQ;;UAGK;EACb;EACA;EACA;EACA;EACA;EACA;EACA,UAAU;EACV;;UAGa;EACb;EACA;EACA;EACA;EACA;;UAGa;EACb,QAAQ;EACR,QAAQ;EACR,WAAW;EACX"}

package/dist/shared/catalog-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"catalog-config.js","names":[],"sources":["../../src/shared/catalog-config.ts"],"sourcesContent":["export type PairMarketDataConfig = {\n    orderbookPriceBuckets: number[];\n};\n\nexport type PairStatus =\n    | \"enabled\"\n    | \"disabled\"\n    | \"cancel_only\"\n    | \"post_only\"\n    | \"reduce_only\"\n    | \"unknown\";\n\nexport const PAIR_STATUSES = [\n    \"enabled\",\n    \"disabled\",\n    \"cancel_only\",\n    \"post_only\",\n    \"reduce_only\",\n] as const satisfies readonly PairStatus[];\n\nexport interface AssetConfig {\n    symbol: string;\n    ledgerId: number;\n    name: string;\n    quantityDisplayDecimals: number;\n    quantityScale: number;\n}\n\nexport interface PairConfig {\n    symbolId: number;\n    symbol: string;\n    baseAsset: string;\n    quoteAsset: string;\n    tickSize: string;\n    stepSize: string;\n    minNotionalQuote: string;\n    minQtyBase: string;\n    allowBuyFeeFromBase: boolean;\n    defaultMarketSlippagePctBuy: number;\n    defaultMarketSlippagePctSell: number;\n    maxClientRefDriftPct: number;\n    marketdata?: PairMarketDataConfig;\n    baseQuantityScale: number;\n    quoteQuantityScale: number;\n    listingAt?: number | null;\n    delistingAt?: number | null;\n    status: PairStatus;\n}\n\nexport interface SpotConfig {\n    assets: AssetConfig[];\n    pairs: PairConfig[];\n    tsSec: number;\n}\n\nexport interface ZipperChainConfig {\n    chainId: number;\n    code: string;\n    name: string;\n    nativeChainId: string;\n    nativeCurrencySymbol: string;\n    explorerUrl: string;\n    icon: string;\n    requiredConfirmations: number;\n    confirmationTimeSeconds: number;\n    isCaseSensitive: boolean;\n    minAddressLength: number;\n    maxAddressLength: number;\n}\n\nexport interface ZipperTokenConfig {\n    address: string;\n    decimals: number;\n}\n\nexport interface ZipperAssetChainVariant {\n    zippedAssetId: number;\n    chainId: number;\n    isNativeAsset: boolean;\n    networkFee: string;\n    networkFeeTsSec: number;\n    depositMinAmount: string;\n    withdrawMinAmount: string;\n    supply: string;\n    sourceToken: ZipperTokenConfig;\n    zToken: ZipperTokenConfig;\n}\n\nexport interface ZipperAssetConfig {\n    asset: string;\n    ledgerId: number;\n    name: string;\n    icon: string;\n    quantityScale: number;\n    quantityDisplayDecimals: number;\n    variants: ZipperAssetChainVariant[];\n    uAssetId: string;\n}\n\nexport interface ZipperChainContractConfig {\n    name: string;\n    address: string;\n    type: string;\n    description: string;\n    version: number;\n}\n\nexport interface DepositWithdrawConfig {\n    chains: ZipperChainConfig[];\n    assets: ZipperAssetConfig[];\n    contracts: ZipperChainContractConfig[];\n    tsMs: number;\n}\n"],"mappings":";AAYA,MAAa,gBAAgB;CACzB;CACA;CACA;CACA;CACA;AACJ"}
+{"version":3,"file":"catalog-config.js","names":[],"sources":["../../src/shared/catalog-config.ts"],"sourcesContent":["export type PairMarketDataConfig = {\n    orderbookPriceBuckets: number[];\n};\n\nexport type PairStatus =\n    | \"enabled\"\n    | \"disabled\"\n    | \"cancel_only\"\n    | \"post_only\"\n    | \"reduce_only\"\n    | \"unknown\";\n\nexport const PAIR_STATUSES = [\n    \"enabled\",\n    \"disabled\",\n    \"cancel_only\",\n    \"post_only\",\n    \"reduce_only\",\n] as const satisfies readonly PairStatus[];\n\nexport interface AssetConfig {\n    symbol: string;\n    ledgerId: number;\n    name: string;\n    quantityDisplayDecimals: number;\n    quantityScale: number;\n    /** Scale for public candle and market-overview base volume. Absent on older snapshots. */\n    marketDataVolumeScale?: number;\n}\n\nexport interface PairConfig {\n    symbolId: number;\n    symbol: string;\n    baseAsset: string;\n    quoteAsset: string;\n    tickSize: string;\n    stepSize: string;\n    minNotionalQuote: string;\n    minQtyBase: string;\n    allowBuyFeeFromBase: boolean;\n    defaultMarketSlippagePctBuy: number;\n    defaultMarketSlippagePctSell: number;\n    maxClientRefDriftPct: number;\n    marketdata?: PairMarketDataConfig;\n    baseQuantityScale: number;\n    quoteQuantityScale: number;\n    /** Scale for composite reference candle prices. Absent on older snapshots. */\n    referencePriceScale?: number;\n    listingAt?: number | null;\n    delistingAt?: number | null;\n    status: PairStatus;\n}\n\nexport interface SpotConfig {\n    assets: AssetConfig[];\n    pairs: PairConfig[];\n    tsSec: number;\n}\n\nexport interface ZipperChainConfig {\n    chainId: number;\n    code: string;\n    name: string;\n    nativeChainId: string;\n    nativeCurrencySymbol: string;\n    explorerUrl: string;\n    icon: string;\n    requiredConfirmations: number;\n    confirmationTimeSeconds: number;\n    isCaseSensitive: boolean;\n    minAddressLength: number;\n    maxAddressLength: number;\n}\n\nexport interface ZipperTokenConfig {\n    address: string;\n    decimals: number;\n}\n\nexport interface ZipperAssetChainVariant {\n    zippedAssetId: number;\n    chainId: number;\n    isNativeAsset: boolean;\n    networkFee: string;\n    networkFeeTsSec: number;\n    depositMinAmount: string;\n    withdrawMinAmount: string;\n    supply: string;\n    sourceToken: ZipperTokenConfig;\n    zToken: ZipperTokenConfig;\n}\n\nexport interface ZipperAssetConfig {\n    asset: string;\n    ledgerId: number;\n    name: string;\n    icon: string;\n    quantityScale: number;\n    quantityDisplayDecimals: number;\n    variants: ZipperAssetChainVariant[];\n    uAssetId: string;\n}\n\nexport interface ZipperChainContractConfig {\n    name: string;\n    address: string;\n    type: string;\n    description: string;\n    version: number;\n}\n\nexport interface DepositWithdrawConfig {\n    chains: ZipperChainConfig[];\n    assets: ZipperAssetConfig[];\n    contracts: ZipperChainContractConfig[];\n    tsMs: number;\n}\n"],"mappings":";AAYA,MAAa,gBAAgB;CACzB;CACA;CACA;CACA;CACA;AACJ"}

package/dist/shared/decimal-surface.d.ts

@@ -10,6 +10,10 @@ interface SdkScales {
   price(): number;
   baseQty(pair: PairCatalogKey): number;
   quoteAmount(pair: PairCatalogKey): number;
+  /** Base volume in public candles and market overview; falls back to the base quantity scale. */
+  marketDataVolume(pair: PairCatalogKey): number;
+  /** Composite reference candle prices; falls back to the primary price scale. */
+  referencePrice(pair: PairCatalogKey): number;
   ledgerAmount(ledgerAssetId: number): number;
   zippedAssetAmount(zippedAssetId: number): number;
 }

package/dist/shared/decimal-surface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decimal-surface.d.ts","names":[],"sources":["../../src/shared/decimal-surface.ts"],"mappings":";;;;;;;UAwCiB;EACb,SAAS;EACT;EACA,QAAQ,MAAM;EACd,YAAY,MAAM;EAClB,aAAa;EACb,kBAAkB"}
+{"version":3,"file":"decimal-surface.d.ts","names":[],"sources":["../../src/shared/decimal-surface.ts"],"mappings":";;;;;;;UAwCiB;EACb,SAAS;EACT;EACA,QAAQ,MAAM;EACd,YAAY,MAAM;;EAElB,iBAAiB,MAAM;;EAEvB,eAAe,MAAM;EACrB,aAAa;EACb,kBAAkB"}

package/dist/shared/decimal-surface.js

@@ -13,6 +13,11 @@ function createCatalogSdkScales(getCatalog) {
 		price: () => 6,
 		baseQty: (pair) => requirePair(getCatalog(), pair).baseAsset.quantityScale,
 		quoteAmount: (pair) => requirePair(getCatalog(), pair).quoteAsset.quantityScale,
+		marketDataVolume: (pair) => {
+			const { baseAsset } = requirePair(getCatalog(), pair);
+			return baseAsset.marketDataVolumeScale ?? baseAsset.quantityScale;
+		},
+		referencePrice: (pair) => requirePair(getCatalog(), pair).referencePriceScale ?? 6,
 		ledgerAmount: (ledgerAssetId) => {
 			const ledger = getCatalog().ledger;
 			if (!ledger.isKnownAssetId(ledgerAssetId)) throw new CatalogLookupError("ledger", "ledgerId", ledgerAssetId);

package/dist/shared/decimal-surface.js.map

@@ -1 +1 @@
-{"version":3,"file":"decimal-surface.js","names":[],"sources":["../../src/shared/decimal-surface.ts"],"sourcesContent":["/**\n * Internal scaled⇄decimal bridge for the SDK's public decimal-string surface.\n *\n * The wire protocol carries scaled integers (price ticks, per-asset scaled\n * quantities); the public SDK surface carries plain decimal strings. Output\n * schemas convert exactly (no rounding, trailing zeros trimmed); input schemas\n * accept zero padding but reject fractional precision that remains above the\n * scale after trailing zeros are removed. Scaled integers must not escape\n * through any service input or output.\n */\nimport {\n    scaledToDecimal,\n    tryDecimalToScaled,\n    type DecimalToScaledFailure,\n} from \"../catalogs/decimal.js\";\nimport {\n    CatalogConversionError,\n    CatalogLookupError,\n    CatalogNotReadyError,\n    type ClientCatalog,\n    type PairCatalogKey,\n} from \"../catalogs/types.js\";\nimport { PRICE_SCALE } from \"../catalogs/readers.js\";\nimport { PROTOBUF_INT64_MAX } from \"./wire-bounds.js\";\n\n/** On-chain unified-asset amounts (`amountE18`) are always 18-decimal scaled. */\nexport const E18_SCALE = 18;\n\n/**\n * Policy notional caps (`max_order_notional`) are canonical quote microunits:\n * one unit is 0.000001 USDT, per the `auth.v1` policy contract. Fixed by the\n * protocol rather than per-pair, so it needs no catalog lookup.\n */\nexport const QUOTE_NOTIONAL_SCALE = 6;\n\n/**\n * Resolves wire scales for the SDK's internal decimal conversion. Backed by\n * the client catalog; `ready()` must be awaited before the synchronous lookups\n * are used so the catalog can answer them.\n */\nexport interface SdkScales {\n    ready(): Promise<void>;\n    price(): number;\n    baseQty(pair: PairCatalogKey): number;\n    quoteAmount(pair: PairCatalogKey): number;\n    ledgerAmount(ledgerAssetId: number): number;\n    zippedAssetAmount(zippedAssetId: number): number;\n}\n\n/**\n * Catalog-backed scale resolver. Takes a getter so it can be constructed\n * before the owning client has assigned its catalog.\n */\nexport function createCatalogSdkScales(getCatalog: () => ClientCatalog): SdkScales {\n    return {\n        ready: async () => {\n            await getCatalog().ensureReady();\n        },\n        price: () => PRICE_SCALE,\n        baseQty: (pair) => requirePair(getCatalog(), pair).baseAsset.quantityScale,\n        quoteAmount: (pair) => requirePair(getCatalog(), pair).quoteAsset.quantityScale,\n        ledgerAmount: (ledgerAssetId) => {\n            const ledger = getCatalog().ledger;\n            if (!ledger.isKnownAssetId(ledgerAssetId)) {\n                throw new CatalogLookupError(\"ledger\", \"ledgerId\", ledgerAssetId);\n            }\n            return ledger.requireAssetByLedgerId(ledgerAssetId).quantityScale;\n        },\n        zippedAssetAmount: (zippedAssetId) =>\n            getCatalog().zipper.requireAssetChainByZippedAssetId(zippedAssetId).asset.quantityScale,\n    };\n}\n\nfunction requirePair(catalog: ClientCatalog, pair: PairCatalogKey) {\n    return typeof pair === \"string\" || (typeof pair === \"object\" && \"symbol\" in pair)\n        ? catalog.market.requirePairBySymbol(typeof pair === \"string\" ? pair : pair.symbol)\n        : catalog.market.requirePairBySymbolId(typeof pair === \"number\" ? pair : pair.symbolId);\n}\n\n/** Output direction: exact scaled→decimal conversion (`1500000n`@6 → `\"1.5\"`). */\nexport function scaledToDecimalOutput(value: bigint, scale: number): string {\n    return scaledToDecimal(value, scale);\n}\n\nfunction conversionFailureMessage(\n    field: string,\n    value: string,\n    failure: DecimalToScaledFailure,\n): string {\n    return failure.reason === \"precision\"\n        ? `${field} supports at most ${failure.maxDecimals} decimal places: ${value}`\n        : `${field} must be a non-negative decimal number: ${value}`;\n}\n\n/**\n * Input direction: strict decimal→scaled conversion. Throws\n * CatalogConversionError for non-decimal input or inexact excess precision.\n */\nexport function decimalInputToScaled(field: string, value: string, scale: number): bigint {\n    const result = tryDecimalToScaled(value.trim(), scale);\n    if (!result.ok) {\n        throw new CatalogConversionError(\n            field,\n            conversionFailureMessage(field, value, result.failure),\n        );\n    }\n    return result.scaled;\n}\n\nfunction unboundedPositiveDecimalInputToScaled(\n    field: string,\n    value: string,\n    scale: number,\n): bigint {\n    const scaled = decimalInputToScaled(field, value, scale);\n    if (scaled <= 0n) {\n        throw new CatalogConversionError(field, `${field} must be greater than 0: ${value}`);\n    }\n    return scaled;\n}\n\n/**\n * Converts a positive decimal input to a scaled protobuf `int64` value.\n * Rejects values above the wire-format ceiling before serialization.\n */\nexport function positiveDecimalInputToScaled(field: string, value: string, scale: number): bigint {\n    const scaled = unboundedPositiveDecimalInputToScaled(field, value, scale);\n    if (scaled > PROTOBUF_INT64_MAX) {\n        throw new CatalogConversionError(\n            field,\n            `${field} exceeds the maximum supported value: ${value}`,\n        );\n    }\n    return scaled;\n}\n\n/**\n * Decimal quantity → PolyesterChain E18 ledger units.\n * Input precision is capped at the asset's quantityScale; the wire value is\n * always upscaled to E18 (trading balances / amount_e18 convention).\n */\nexport function quantityInputToE18(params: {\n    scales: SdkScales;\n    assetId: number;\n    quantity: string;\n    field?: string;\n}): bigint {\n    const field = params.field ?? \"quantity\";\n    const assetScale = params.scales.ledgerAmount(params.assetId);\n    if (assetScale > E18_SCALE) {\n        throw new CatalogConversionError(\n            field,\n            `${field} asset quantityScale ${assetScale} exceeds E18 ledger scale`,\n        );\n    }\n    return (\n        unboundedPositiveDecimalInputToScaled(field, params.quantity, assetScale) *\n        10n ** BigInt(E18_SCALE - assetScale)\n    );\n}\n\nexport interface ReadyGate {\n    /** Queues or delivers one transition while the gate remains active. */\n    run(deliver: () => void): void;\n    /** Drops pending transitions and permanently prevents future delivery. */\n    close(): void;\n}\n\ninterface ReadyGateHandlers {\n    onDeliveryError?: (error: unknown) => void;\n    onTerminalError: (error: unknown) => void;\n}\n\nconst READY_GATE_MAX_PENDING_DELIVERIES = 1_024;\n\n/**\n * Transition event delivery behind catalog readiness. Events arriving before the\n * catalog can resolve scales are queued and flushed in arrival order once it\n * is ready. Delivery errors are isolated from the transport. Readiness failure\n * or queue overflow is terminal because dropping an event would break stream\n * continuity; the owning subscription must visibly terminate when notified.\n */\nexport function createReadyGate(\n    ready: () => Promise<void>,\n    handlers: ReadyGateHandlers,\n): ReadyGate {\n    let state: \"pending\" | \"open\" | \"closed\" = \"pending\";\n    const queue: Array<() => void> = [];\n\n    const deliverIsolated = (deliver: () => void) => {\n        try {\n            deliver();\n        } catch (error) {\n            handlers.onDeliveryError?.(error);\n        }\n    };\n\n    const closeWithError = (error: unknown) => {\n        if (state === \"closed\") return;\n        state = \"closed\";\n        queue.length = 0;\n        handlers.onTerminalError(error);\n    };\n\n    Promise.resolve()\n        .then(ready)\n        .then(\n            () => {\n                if (state !== \"pending\") return;\n                state = \"open\";\n                for (const deliver of queue.splice(0)) deliverIsolated(deliver);\n            },\n            (error) => {\n                if (state !== \"pending\") return;\n                closeWithError(error);\n            },\n        );\n\n    return {\n        run(deliver) {\n            if (state === \"open\") deliverIsolated(deliver);\n            else if (state === \"pending\") {\n                if (queue.length === READY_GATE_MAX_PENDING_DELIVERIES) {\n                    closeWithError(new CatalogNotReadyError());\n                    return;\n                }\n                queue.push(deliver);\n            }\n        },\n        close() {\n            if (state === \"closed\") return;\n            state = \"closed\";\n            queue.length = 0;\n        },\n    };\n}\n"],"mappings":"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"}
+{"version":3,"file":"decimal-surface.js","names":[],"sources":["../../src/shared/decimal-surface.ts"],"sourcesContent":["/**\n * Internal scaled⇄decimal bridge for the SDK's public decimal-string surface.\n *\n * The wire protocol carries scaled integers (price ticks, per-asset scaled\n * quantities); the public SDK surface carries plain decimal strings. Output\n * schemas convert exactly (no rounding, trailing zeros trimmed); input schemas\n * accept zero padding but reject fractional precision that remains above the\n * scale after trailing zeros are removed. Scaled integers must not escape\n * through any service input or output.\n */\nimport {\n    scaledToDecimal,\n    tryDecimalToScaled,\n    type DecimalToScaledFailure,\n} from \"../catalogs/decimal.js\";\nimport {\n    CatalogConversionError,\n    CatalogLookupError,\n    CatalogNotReadyError,\n    type ClientCatalog,\n    type PairCatalogKey,\n} from \"../catalogs/types.js\";\nimport { PRICE_SCALE } from \"../catalogs/readers.js\";\nimport { PROTOBUF_INT64_MAX } from \"./wire-bounds.js\";\n\n/** On-chain unified-asset amounts (`amountE18`) are always 18-decimal scaled. */\nexport const E18_SCALE = 18;\n\n/**\n * Policy notional caps (`max_order_notional`) are canonical quote microunits:\n * one unit is 0.000001 USDT, per the `auth.v1` policy contract. Fixed by the\n * protocol rather than per-pair, so it needs no catalog lookup.\n */\nexport const QUOTE_NOTIONAL_SCALE = 6;\n\n/**\n * Resolves wire scales for the SDK's internal decimal conversion. Backed by\n * the client catalog; `ready()` must be awaited before the synchronous lookups\n * are used so the catalog can answer them.\n */\nexport interface SdkScales {\n    ready(): Promise<void>;\n    price(): number;\n    baseQty(pair: PairCatalogKey): number;\n    quoteAmount(pair: PairCatalogKey): number;\n    /** Base volume in public candles and market overview; falls back to the base quantity scale. */\n    marketDataVolume(pair: PairCatalogKey): number;\n    /** Composite reference candle prices; falls back to the primary price scale. */\n    referencePrice(pair: PairCatalogKey): number;\n    ledgerAmount(ledgerAssetId: number): number;\n    zippedAssetAmount(zippedAssetId: number): number;\n}\n\n/**\n * Catalog-backed scale resolver. Takes a getter so it can be constructed\n * before the owning client has assigned its catalog.\n */\nexport function createCatalogSdkScales(getCatalog: () => ClientCatalog): SdkScales {\n    return {\n        ready: async () => {\n            await getCatalog().ensureReady();\n        },\n        price: () => PRICE_SCALE,\n        baseQty: (pair) => requirePair(getCatalog(), pair).baseAsset.quantityScale,\n        quoteAmount: (pair) => requirePair(getCatalog(), pair).quoteAsset.quantityScale,\n        marketDataVolume: (pair) => {\n            const { baseAsset } = requirePair(getCatalog(), pair);\n            return baseAsset.marketDataVolumeScale ?? baseAsset.quantityScale;\n        },\n        referencePrice: (pair) =>\n            requirePair(getCatalog(), pair).referencePriceScale ?? PRICE_SCALE,\n        ledgerAmount: (ledgerAssetId) => {\n            const ledger = getCatalog().ledger;\n            if (!ledger.isKnownAssetId(ledgerAssetId)) {\n                throw new CatalogLookupError(\"ledger\", \"ledgerId\", ledgerAssetId);\n            }\n            return ledger.requireAssetByLedgerId(ledgerAssetId).quantityScale;\n        },\n        zippedAssetAmount: (zippedAssetId) =>\n            getCatalog().zipper.requireAssetChainByZippedAssetId(zippedAssetId).asset.quantityScale,\n    };\n}\n\nfunction requirePair(catalog: ClientCatalog, pair: PairCatalogKey) {\n    return typeof pair === \"string\" || (typeof pair === \"object\" && \"symbol\" in pair)\n        ? catalog.market.requirePairBySymbol(typeof pair === \"string\" ? pair : pair.symbol)\n        : catalog.market.requirePairBySymbolId(typeof pair === \"number\" ? pair : pair.symbolId);\n}\n\n/** Output direction: exact scaled→decimal conversion (`1500000n`@6 → `\"1.5\"`). */\nexport function scaledToDecimalOutput(value: bigint, scale: number): string {\n    return scaledToDecimal(value, scale);\n}\n\nfunction conversionFailureMessage(\n    field: string,\n    value: string,\n    failure: DecimalToScaledFailure,\n): string {\n    return failure.reason === \"precision\"\n        ? `${field} supports at most ${failure.maxDecimals} decimal places: ${value}`\n        : `${field} must be a non-negative decimal number: ${value}`;\n}\n\n/**\n * Input direction: strict decimal→scaled conversion. Throws\n * CatalogConversionError for non-decimal input or inexact excess precision.\n */\nexport function decimalInputToScaled(field: string, value: string, scale: number): bigint {\n    const result = tryDecimalToScaled(value.trim(), scale);\n    if (!result.ok) {\n        throw new CatalogConversionError(\n            field,\n            conversionFailureMessage(field, value, result.failure),\n        );\n    }\n    return result.scaled;\n}\n\nfunction unboundedPositiveDecimalInputToScaled(\n    field: string,\n    value: string,\n    scale: number,\n): bigint {\n    const scaled = decimalInputToScaled(field, value, scale);\n    if (scaled <= 0n) {\n        throw new CatalogConversionError(field, `${field} must be greater than 0: ${value}`);\n    }\n    return scaled;\n}\n\n/**\n * Converts a positive decimal input to a scaled protobuf `int64` value.\n * Rejects values above the wire-format ceiling before serialization.\n */\nexport function positiveDecimalInputToScaled(field: string, value: string, scale: number): bigint {\n    const scaled = unboundedPositiveDecimalInputToScaled(field, value, scale);\n    if (scaled > PROTOBUF_INT64_MAX) {\n        throw new CatalogConversionError(\n            field,\n            `${field} exceeds the maximum supported value: ${value}`,\n        );\n    }\n    return scaled;\n}\n\n/**\n * Decimal quantity → PolyesterChain E18 ledger units.\n * Input precision is capped at the asset's quantityScale; the wire value is\n * always upscaled to E18 (trading balances / amount_e18 convention).\n */\nexport function quantityInputToE18(params: {\n    scales: SdkScales;\n    assetId: number;\n    quantity: string;\n    field?: string;\n}): bigint {\n    const field = params.field ?? \"quantity\";\n    const assetScale = params.scales.ledgerAmount(params.assetId);\n    if (assetScale > E18_SCALE) {\n        throw new CatalogConversionError(\n            field,\n            `${field} asset quantityScale ${assetScale} exceeds E18 ledger scale`,\n        );\n    }\n    return (\n        unboundedPositiveDecimalInputToScaled(field, params.quantity, assetScale) *\n        10n ** BigInt(E18_SCALE - assetScale)\n    );\n}\n\nexport interface ReadyGate {\n    /** Queues or delivers one transition while the gate remains active. */\n    run(deliver: () => void): void;\n    /** Drops pending transitions and permanently prevents future delivery. */\n    close(): void;\n}\n\ninterface ReadyGateHandlers {\n    onDeliveryError?: (error: unknown) => void;\n    onTerminalError: (error: unknown) => void;\n}\n\nconst READY_GATE_MAX_PENDING_DELIVERIES = 1_024;\n\n/**\n * Transition event delivery behind catalog readiness. Events arriving before the\n * catalog can resolve scales are queued and flushed in arrival order once it\n * is ready. Delivery errors are isolated from the transport. Readiness failure\n * or queue overflow is terminal because dropping an event would break stream\n * continuity; the owning subscription must visibly terminate when notified.\n */\nexport function createReadyGate(\n    ready: () => Promise<void>,\n    handlers: ReadyGateHandlers,\n): ReadyGate {\n    let state: \"pending\" | \"open\" | \"closed\" = \"pending\";\n    const queue: Array<() => void> = [];\n\n    const deliverIsolated = (deliver: () => void) => {\n        try {\n            deliver();\n        } catch (error) {\n            handlers.onDeliveryError?.(error);\n        }\n    };\n\n    const closeWithError = (error: unknown) => {\n        if (state === \"closed\") return;\n        state = \"closed\";\n        queue.length = 0;\n        handlers.onTerminalError(error);\n    };\n\n    Promise.resolve()\n        .then(ready)\n        .then(\n            () => {\n                if (state !== \"pending\") return;\n                state = \"open\";\n                for (const deliver of queue.splice(0)) deliverIsolated(deliver);\n            },\n            (error) => {\n                if (state !== \"pending\") return;\n                closeWithError(error);\n            },\n        );\n\n    return {\n        run(deliver) {\n            if (state === \"open\") deliverIsolated(deliver);\n            else if (state === \"pending\") {\n                if (queue.length === READY_GATE_MAX_PENDING_DELIVERIES) {\n                    closeWithError(new CatalogNotReadyError());\n                    return;\n                }\n                queue.push(deliver);\n            }\n        },\n        close() {\n            if (state === \"closed\") return;\n            state = \"closed\";\n            queue.length = 0;\n        },\n    };\n}\n"],"mappings":";;;;;;;AAyDA,SAAgB,uBAAuB,YAA4C;CAC/E,OAAO;EACH,OAAO,YAAY;GACf,MAAM,WAAW,CAAC,CAAC,YAAY;EACnC;EACA,aAAA;EACA,UAAU,SAAS,YAAY,WAAW,GAAG,IAAI,CAAC,CAAC,UAAU;EAC7D,cAAc,SAAS,YAAY,WAAW,GAAG,IAAI,CAAC,CAAC,WAAW;EAClE,mBAAmB,SAAS;GACxB,MAAM,EAAE,cAAc,YAAY,WAAW,GAAG,IAAI;GACpD,OAAO,UAAU,yBAAyB,UAAU;EACxD;EACA,iBAAiB,SACb,YAAY,WAAW,GAAG,IAAI,CAAC,CAAC,uBAAA;EACpC,eAAe,kBAAkB;GAC7B,MAAM,SAAS,WAAW,CAAC,CAAC;GAC5B,IAAI,CAAC,OAAO,eAAe,aAAa,GACpC,MAAM,IAAI,mBAAmB,UAAU,YAAY,aAAa;GAEpE,OAAO,OAAO,uBAAuB,aAAa,CAAC,CAAC;EACxD;EACA,oBAAoB,kBAChB,WAAW,CAAC,CAAC,OAAO,iCAAiC,aAAa,CAAC,CAAC,MAAM;CAClF;AACJ;AAEA,SAAS,YAAY,SAAwB,MAAsB;CAC/D,OAAO,OAAO,SAAS,YAAa,OAAO,SAAS,YAAY,YAAY,OACtE,QAAQ,OAAO,oBAAoB,OAAO,SAAS,WAAW,OAAO,KAAK,MAAM,IAChF,QAAQ,OAAO,sBAAsB,OAAO,SAAS,WAAW,OAAO,KAAK,QAAQ;AAC9F;;AAGA,SAAgB,sBAAsB,OAAe,OAAuB;CACxE,OAAO,gBAAgB,OAAO,KAAK;AACvC;AAEA,SAAS,yBACL,OACA,OACA,SACM;CACN,OAAO,QAAQ,WAAW,cACpB,GAAG,MAAM,oBAAoB,QAAQ,YAAY,mBAAmB,UACpE,GAAG,MAAM,0CAA0C;AAC7D;;;;;AAMA,SAAgB,qBAAqB,OAAe,OAAe,OAAuB;CACtF,MAAM,SAAS,mBAAmB,MAAM,KAAK,GAAG,KAAK;CACrD,IAAI,CAAC,OAAO,IACR,MAAM,IAAI,uBACN,OACA,yBAAyB,OAAO,OAAO,OAAO,OAAO,CACzD;CAEJ,OAAO,OAAO;AAClB;AAEA,SAAS,sCACL,OACA,OACA,OACM;CACN,MAAM,SAAS,qBAAqB,OAAO,OAAO,KAAK;CACvD,IAAI,UAAU,IACV,MAAM,IAAI,uBAAuB,OAAO,GAAG,MAAM,2BAA2B,OAAO;CAEvF,OAAO;AACX;;;;;AAMA,SAAgB,6BAA6B,OAAe,OAAe,OAAuB;CAC9F,MAAM,SAAS,sCAAsC,OAAO,OAAO,KAAK;CACxE,IAAI,SAAA,sBACA,MAAM,IAAI,uBACN,OACA,GAAG,MAAM,wCAAwC,OACrD;CAEJ,OAAO;AACX;;;;;;AAOA,SAAgB,mBAAmB,QAKxB;CACP,MAAM,QAAQ,OAAO,SAAS;CAC9B,MAAM,aAAa,OAAO,OAAO,aAAa,OAAO,OAAO;CAC5D,IAAI,aAAA,IACA,MAAM,IAAI,uBACN,OACA,GAAG,MAAM,uBAAuB,WAAW,0BAC/C;CAEJ,OACI,sCAAsC,OAAO,OAAO,UAAU,UAAU,IACxE,OAAO,OAAA,KAAmB,UAAU;AAE5C;AAcA,MAAM,oCAAoC;;;;;;;;AAS1C,SAAgB,gBACZ,OACA,UACS;CACT,IAAI,QAAuC;CAC3C,MAAM,QAA2B,CAAC;CAElC,MAAM,mBAAmB,YAAwB;EAC7C,IAAI;GACA,QAAQ;EACZ,SAAS,OAAO;GACZ,SAAS,kBAAkB,KAAK;EACpC;CACJ;CAEA,MAAM,kBAAkB,UAAmB;EACvC,IAAI,UAAU,UAAU;EACxB,QAAQ;EACR,MAAM,SAAS;EACf,SAAS,gBAAgB,KAAK;CAClC;CAEA,QAAQ,QAAQ,CAAC,CACZ,KAAK,KAAK,CAAC,CACX,WACS;EACF,IAAI,UAAU,WAAW;EACzB,QAAQ;EACR,KAAK,MAAM,WAAW,MAAM,OAAO,CAAC,GAAG,gBAAgB,OAAO;CAClE,IACC,UAAU;EACP,IAAI,UAAU,WAAW;EACzB,eAAe,KAAK;CACxB,CACJ;CAEJ,OAAO;EACH,IAAI,SAAS;GACT,IAAI,UAAU,QAAQ,gBAAgB,OAAO;QACxC,IAAI,UAAU,WAAW;IAC1B,IAAI,MAAM,WAAW,mCAAmC;KACpD,eAAe,IAAI,qBAAqB,CAAC;KACzC;IACJ;IACA,MAAM,KAAK,OAAO;GACtB;EACJ;EACA,QAAQ;GACJ,IAAI,UAAU,UAAU;GACxB,QAAQ;GACR,MAAM,SAAS;EACnB;CACJ;AACJ"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@polyester/sdk",
-    "version": "0.27.1",
+    "version": "0.27.2",
     "private": false,
     "description": "TypeScript SDK providing access to APIs on Polyester Exchange.",
     "homepage": "https://github.com/Fabric-Labs/polyester-sdk-typescript#readme",
@@ -106,7 +106,9 @@
     "devDependencies": {
         "@changesets/cli": "2.31.1",
         "@changesets/get-github-info": "0.8.0",
+        "@fast-check/vitest": "0.5.0",
         "@types/bun": "1.3.14",
+        "fast-check": "4.10.2",
         "oxfmt": "0.61.0",
         "oxlint": "1.76.0",
         "pkg-pr-new": "0.0.88",