@signals-protocol/v1-sdk 1.0.0

package/README.md

@@ -0,0 +1,99 @@
+# Signals v1 SDK
+
+Contract-aligned TypeScript SDK for Signals v1 CLMSR market math. Quote open and
+close costs, compute inverse quantities, and map subgraph data into calculation
+types.
+
+## Install
+
+```bash
+npm install @signals-protocol/v1-sdk
+```
+
+## Quick start
+
+```ts
+import {
+  CLMSRSDK,
+  mapMarket,
+  mapDistribution,
+  toMicroUSDC,
+} from "@signals-protocol/v1-sdk";
+
+const sdk = new CLMSRSDK();
+
+// Raw data from your subgraph (strings)
+const rawMarket = {
+  liquidityParameter: "1000000000000000000",
+  minTick: -500,
+  maxTick: 500,
+  tickSpacing: 10,
+};
+
+const rawDistribution = {
+  totalSum: "1000000000000000000",
+  binFactors: ["1000000000000000000", "1000000000000000000"],
+};
+
+const market = mapMarket(rawMarket);
+const distribution = mapDistribution(rawDistribution);
+
+const quantity = toMicroUSDC(10); // 10 USDC in 6 decimals
+const quote = sdk.calculateOpenCost(-100, 100, quantity, distribution, market);
+
+console.log(quote.cost.toString());
+```
+
+## Common tasks
+
+### Quote sell proceeds
+
+```ts
+import { CLMSRSDK, toMicroUSDC } from "@signals-protocol/v1-sdk";
+
+const sdk = new CLMSRSDK();
+
+const position = {
+  lowerTick: -100,
+  upperTick: 100,
+  quantity: toMicroUSDC(10),
+};
+
+const proceeds = sdk.calculateDecreaseProceeds(
+  position,
+  toMicroUSDC(5),
+  distribution,
+  market
+);
+
+console.log(proceeds.proceeds.toString());
+```
+
+### Inverse: budget to quantity
+
+```ts
+const result = sdk.calculateQuantityFromCost(
+  -100,
+  100,
+  toMicroUSDC(50),
+  distribution,
+  market,
+  true
+);
+
+console.log(result.quantity.toString());
+```
+
+## Exports
+
+- `CLMSRSDK` / `SignalsSDK` for pricing and inverse functions
+- `createCLMSRSDK`, `createSignalsSDK` convenience constructors
+- `mapMarket`, `mapDistribution` for GraphQL-to-SDK conversions
+- `MathUtils` for WAD/USDC helpers and math utilities
+- Types in `types.ts` (e.g. `Market`, `MarketDistribution`, `Position`, `FeeInfo`)
+
+## Notes
+
+- Amounts are `big.js` values (USDC uses 6 decimals, WAD uses 18 decimals).
+- Fee overlays follow the contract fee policy descriptor when provided.
+- The SDK mirrors contract math and overflow guards for compatibility.

package/dist/clmsr-sdk.d.ts

@@ -0,0 +1,110 @@
+import { MarketDistribution, Market, Position, OpenCostResult, IncreaseCostResult, DecreaseProceedsResult, CloseProceedsResult, ClaimResult, QuantityFromCostResult, QuantityFromProceedsResult, PositionValueResult, USDCAmount, Quantity, Tick } from "./types";
+export * from "./types";
+export { toWAD, toMicroUSDC } from "./utils/math";
+/**
+ * CLMSR SDK - 컨트랙트 뷰함수들과 역함수 제공
+ */
+export declare class CLMSRSDK {
+    /**
+     * calculateOpenCost - 새 포지션 열기 비용 계산
+     * @param lowerTick Lower tick bound (inclusive)
+     * @param upperTick Upper tick bound (exclusive)
+     * @param quantity 매수 수량
+     * @param distribution Current market distribution
+     * @param market Market parameters
+     */
+    calculateOpenCost(lowerTick: Tick, upperTick: Tick, quantity: Quantity, distribution: MarketDistribution, market: Market): OpenCostResult;
+    /**
+     * calculateIncreaseCost - 기존 포지션 증가 비용 계산
+     */
+    calculateIncreaseCost(position: Position, additionalQuantity: Quantity, distribution: MarketDistribution, market: Market): IncreaseCostResult;
+    /**
+     * Decrease position 비용 계산
+     */
+    calculateDecreaseProceeds(position: Position, sellQuantity: Quantity, distribution: MarketDistribution, market: Market): DecreaseProceedsResult;
+    /**
+     * Close position 비용 계산
+     */
+    calculateCloseProceeds(position: Position, distribution: MarketDistribution, market: Market): CloseProceedsResult;
+    /**
+     * Claim amount 계산
+     */
+    calculateClaim(position: Position, settlementTick: Tick): ClaimResult;
+    /**
+     * 포지션의 현재 가치와 미실현 손익 계산
+     * @param position 포지션 정보
+     * @param totalCost 포지션의 총 비용 (OPEN + INCREASE 비용 합계)
+     * @param distribution Current market distribution
+     * @param market Market parameters
+     * @returns 포지션 현재 가치와 미실현 손익
+     */
+    calculatePositionValue(position: Position, totalCost: USDCAmount, distribution: MarketDistribution, market: Market): PositionValueResult;
+    /**
+     * Sell position의 예상 수익 계산
+     * @param position 포지션 정보
+     * @param sellQuantity 매도할 수량
+     * @param distribution Current market distribution
+     * @param market Market parameters
+     * @returns 예상 수익
+     */
+    calculateSellProceeds(position: Position, sellQuantity: Quantity, distribution: MarketDistribution, market: Market): DecreaseProceedsResult;
+    /**
+     * 주어진 총 지출(수수료 포함)으로 살 수 있는 수량 계산 (역산)
+     * @param lowerTick Lower tick bound (inclusive)
+     * @param upperTick Upper tick bound (exclusive)
+     * @param cost 총 지출 한도 (수수료 포함, 6 decimals)
+     * @param distribution Current market distribution
+     * @param market Market parameters
+     * @returns 구매 가능한 수량과 순수 베팅 비용
+     */
+    calculateQuantityFromCost(lowerTick: Tick, upperTick: Tick, cost: USDCAmount, distribution: MarketDistribution, market: Market, includeFees?: boolean): QuantityFromCostResult;
+    private _calculateQuantityFromNetCost;
+    private _computeTotalSpendWithFees;
+    /**
+     * 주어진 목표 수익(수수료 반영)으로 필요한 매도 수량 역산
+     * @param position 보유 포지션 정보
+     * @param targetProceeds 수수료 제외 후 실제로 받고 싶은 금액 (6 decimals)
+     * @param distribution Current market distribution
+     * @param market Market parameters
+     * @returns 매도해야 할 수량과 검증된 실제 수익(수수료 제외 전 기준)
+     */
+    calculateQuantityFromProceeds(position: Position, targetProceeds: USDCAmount, distribution: MarketDistribution, market: Market, includeFees?: boolean): QuantityFromProceedsResult;
+    /**
+     * 시장별 최대 수량 한계 검증 (컨트랙트와 동일한 제한)
+     * @param quantity 검증할 수량 (6 decimals)
+     * @param alpha 유동성 파라미터 α (18 decimals WAD)
+     * @throws Error if quantity exceeds market limit
+     */
+    private _assertQuantityWithinLimit;
+    private _calculateTradeCostWad;
+    private _calculateSingleTradeCostWad;
+    private _calculateTradeCostChunked;
+    private _calculateSellProceedsWad;
+    private _calculateSingleSellProceedsWad;
+    private _calculateSellProceedsChunked;
+    private _computeSafeChunk;
+    /**
+     * 내부 헬퍼: 매도 수익 계산 (코드 중복 제거)
+     * @param lowerTick Lower tick bound (inclusive)
+     * @param upperTick Upper tick bound (exclusive)
+     * @param sellQuantity 매도할 수량
+     * @param positionQuantity 현재 포지션 수량 (검증용)
+     * @param distribution Current market distribution
+     * @param market Market parameters
+     * @returns 매도 수익
+     */
+    private _calculateQuantityFromBaseProceeds;
+    private _calcSellProceeds;
+    private _computeNetProceedsAfterFees;
+    private computeFeeOverlay;
+    private validateTickRange;
+    private getAffectedSum;
+}
+/**
+ * Create CLMSR SDK instance
+ */
+export declare function createCLMSRSDK(): CLMSRSDK;
+/**
+ * Create Signals SDK instance (v1 alias)
+ */
+export declare function createSignalsSDK(): CLMSRSDK;