@signals-protocol/v1-sdk 1.0.0

package/dist/fees.d.ts

@@ -0,0 +1,69 @@
+import { BigNumberish } from "ethers";
+export type TradeSide = "BUY" | "SELL";
+export type Bytes32Like = `0x${string}`;
+interface FeeQuoteParams {
+    trader: string;
+    marketId: bigint;
+    lowerTick: bigint;
+    upperTick: bigint;
+    quantity6: bigint;
+    baseAmount6: bigint;
+    side: TradeSide;
+    context: Bytes32Like;
+}
+export interface FeePolicy {
+    quote(params: FeeQuoteParams): bigint;
+    name?: string;
+}
+export declare const NullFeePolicy: FeePolicy;
+export interface PercentageFeePolicyConfig {
+    bps: BigNumberish;
+    name?: string;
+}
+export interface CustomFeePolicyConfig {
+    bps: BigNumberish;
+    name?: string;
+}
+export declare function createPercentageFeePolicy(config: PercentageFeePolicyConfig): FeePolicy;
+export declare function createCustomFeePolicy(config: CustomFeePolicyConfig): FeePolicy;
+export type FeePolicyName = "Null" | "Percentage" | "Custom";
+export declare function getFeePolicy(name: "Null"): FeePolicy;
+export declare function getFeePolicy(name: "Percentage", config: PercentageFeePolicyConfig): FeePolicy;
+export declare function getFeePolicy(name: "Custom", config: CustomFeePolicyConfig): FeePolicy;
+export interface PreviewOpenFeeArgs {
+    trader: string;
+    marketId: BigNumberish;
+    lowerTick: BigNumberish;
+    upperTick: BigNumberish;
+    quantity6: BigNumberish;
+    cost6: BigNumberish;
+    context?: Bytes32Like;
+}
+export interface PreviewSellFeeArgs {
+    trader: string;
+    marketId: BigNumberish;
+    lowerTick: BigNumberish;
+    upperTick: BigNumberish;
+    sellQuantity6: BigNumberish;
+    proceeds6: BigNumberish;
+    context?: Bytes32Like;
+}
+interface ParsedFeePolicyDescriptor {
+    policy: "null" | "percentage" | "custom";
+    name?: string;
+    bps?: bigint;
+    descriptor: string;
+}
+export interface EncodePercentageFeePolicyDescriptorParams {
+    bps: BigNumberish;
+    name?: string;
+}
+export interface ResolvedFeePolicy {
+    policy: FeePolicy;
+    descriptor?: ParsedFeePolicyDescriptor;
+}
+export declare function resolveFeePolicyWithMetadata(input: FeePolicy | string): ResolvedFeePolicy;
+declare function quoteOpenFee(policyInput: FeePolicy | string, args: PreviewOpenFeeArgs): bigint;
+declare function quoteSellFee(policyInput: FeePolicy | string, args: PreviewSellFeeArgs): bigint;
+export declare function encodePercentageFeePolicyDescriptor(params: EncodePercentageFeePolicyDescriptorParams): string;
+export { quoteOpenFee, quoteSellFee };

package/dist/fees.js

@@ -0,0 +1,229 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NullFeePolicy = void 0;
+exports.createPercentageFeePolicy = createPercentageFeePolicy;
+exports.createCustomFeePolicy = createCustomFeePolicy;
+exports.getFeePolicy = getFeePolicy;
+exports.resolveFeePolicyWithMetadata = resolveFeePolicyWithMetadata;
+exports.encodePercentageFeePolicyDescriptor = encodePercentageFeePolicyDescriptor;
+exports.quoteOpenFee = quoteOpenFee;
+exports.quoteSellFee = quoteSellFee;
+const ethers_1 = require("ethers");
+const ZERO_CONTEXT = `0x${"00".repeat(32)}`;
+const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+function toBigInt(value) {
+    return (0, ethers_1.toBigInt)(value);
+}
+function normalizeContext(context) {
+    return (context ?? ZERO_CONTEXT);
+}
+function normalizeTrader(trader) {
+    if (!trader) {
+        return ZERO_ADDRESS;
+    }
+    return trader;
+}
+function normalizeMarketId(marketId) {
+    if (marketId === undefined || marketId === null) {
+        return 0n;
+    }
+    return toBigInt(marketId);
+}
+exports.NullFeePolicy = Object.freeze({
+    quote: () => 0n,
+    name: "NullFeePolicy",
+});
+function createPercentageFeePolicy(config) {
+    const bps = toBigInt(config.bps);
+    const policyName = config.name ?? "PercentageFeePolicy";
+    return {
+        name: policyName,
+        quote: ({ baseAmount6 }) => {
+            return (baseAmount6 * bps) / 10000n;
+        },
+    };
+}
+function createCustomFeePolicy(config) {
+    const bps = toBigInt(config.bps);
+    const policyName = config.name ?? "CustomFeePolicy";
+    return {
+        name: policyName,
+        quote: ({ baseAmount6 }) => {
+            return (baseAmount6 * bps) / 10000n;
+        },
+    };
+}
+const FeePolicies = Object.freeze({
+    Null: exports.NullFeePolicy,
+    Percentage: (config) => createPercentageFeePolicy(config),
+    Custom: (config) => createCustomFeePolicy(config),
+});
+function getFeePolicy(name, config) {
+    if (name === "Null") {
+        return FeePolicies.Null;
+    }
+    if (name === "Percentage") {
+        if (!config) {
+            throw new Error("Percentage fee policy requires configuration");
+        }
+        return createPercentageFeePolicy(config);
+    }
+    if (name === "Custom") {
+        if (!config) {
+            throw new Error("Custom fee policy requires configuration");
+        }
+        return createCustomFeePolicy(config);
+    }
+    throw new Error(`Unsupported fee policy: ${name}`);
+}
+function buildQuoteParams(side, args) {
+    return {
+        trader: normalizeTrader(args.trader),
+        marketId: normalizeMarketId(args.marketId),
+        lowerTick: toBigInt(args.lowerTick),
+        upperTick: toBigInt(args.upperTick),
+        quantity6: side === "BUY"
+            ? toBigInt(args.quantity6)
+            : toBigInt(args.sellQuantity6),
+        baseAmount6: side === "BUY"
+            ? toBigInt(args.cost6)
+            : toBigInt(args.proceeds6),
+        side,
+        context: normalizeContext(args.context),
+    };
+}
+function parseBigIntParam(value, field, options) {
+    if (value === undefined || value === null) {
+        if (options?.required) {
+            throw new Error(`Missing required parameter '${field}' in fee policy descriptor`);
+        }
+        return undefined;
+    }
+    try {
+        return toBigInt(value);
+    }
+    catch {
+        throw new Error(`Invalid value for '${field}' in fee policy descriptor: ${value}`);
+    }
+}
+function parseFeePolicyDescriptor(descriptor) {
+    let parsed;
+    try {
+        parsed = JSON.parse(descriptor);
+    }
+    catch (error) {
+        throw new Error(`Invalid fee policy descriptor: ${descriptor}. ${String(error)}`);
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        throw new Error("Fee policy descriptor must be a JSON object");
+    }
+    const { policy, params } = parsed;
+    if (!policy || typeof policy !== "string") {
+        throw new Error("Fee policy descriptor must include a string 'policy' field");
+    }
+    const normalizedPolicy = policy.toLowerCase();
+    const paramBag = params ?? {};
+    if (normalizedPolicy === "null") {
+        return {
+            policy: "null",
+            name: typeof paramBag.name === "string"
+                ? paramBag.name
+                : parsed && typeof parsed.name === "string"
+                    ? parsed.name
+                    : undefined,
+            descriptor,
+        };
+    }
+    if (normalizedPolicy === "percentage") {
+        const bps = parseBigIntParam(paramBag.bps, "bps", {
+            required: true,
+        });
+        const name = typeof paramBag.name === "string"
+            ? paramBag.name
+            : typeof parsed.name === "string"
+                ? parsed.name
+                : undefined;
+        return {
+            policy: "percentage",
+            name,
+            bps,
+            descriptor,
+        };
+    }
+    if (normalizedPolicy === "custom") {
+        const bps = parseBigIntParam(paramBag.bps, "bps", {
+            required: true,
+        });
+        const name = typeof paramBag.name === "string"
+            ? paramBag.name
+            : typeof parsed.name === "string"
+                ? parsed.name
+                : undefined;
+        return {
+            policy: "custom",
+            name,
+            bps,
+            descriptor,
+        };
+    }
+    throw new Error(`Unsupported fee policy '${policy}' in descriptor`);
+}
+function resolveFeePolicyWithMetadata(input) {
+    if (typeof input !== "string") {
+        return { policy: input };
+    }
+    const parsed = parseFeePolicyDescriptor(input);
+    if (parsed.policy === "null") {
+        if (parsed.name && parsed.name !== exports.NullFeePolicy.name) {
+            return {
+                policy: {
+                    quote: exports.NullFeePolicy.quote,
+                    name: parsed.name,
+                },
+                descriptor: parsed,
+            };
+        }
+        return { policy: exports.NullFeePolicy, descriptor: parsed };
+    }
+    if (parsed.policy === "custom") {
+        const customPolicy = createCustomFeePolicy({
+            bps: parsed.bps,
+            name: parsed.name,
+        });
+        return {
+            policy: customPolicy,
+            descriptor: parsed,
+        };
+    }
+    const percentagePolicy = createPercentageFeePolicy({
+        bps: parsed.bps,
+        name: parsed.name,
+    });
+    return {
+        policy: percentagePolicy,
+        descriptor: parsed,
+    };
+}
+function quoteOpenFee(policyInput, args) {
+    const { policy } = resolveFeePolicyWithMetadata(policyInput);
+    return policy.quote(buildQuoteParams("BUY", args));
+}
+function quoteSellFee(policyInput, args) {
+    const { policy } = resolveFeePolicyWithMetadata(policyInput);
+    return policy.quote(buildQuoteParams("SELL", args));
+}
+function encodePercentageFeePolicyDescriptor(params) {
+    const bps = toBigInt(params.bps);
+    if (bps < 0n) {
+        throw new Error("Fee bps must be non-negative");
+    }
+    const descriptor = {
+        policy: "percentage",
+        params: {
+            bps: bps.toString(),
+            ...(params.name ? { name: params.name } : {}),
+        },
+        ...(params.name ? { name: params.name } : {}),
+    };
+    return JSON.stringify(descriptor);
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Signals v1 SDK for TypeScript
+ *
+ * 컨트랙트 뷰함수들과 역함수 제공
+ */
+export { CLMSRSDK } from "./clmsr-sdk";
+export { CLMSRSDK as SignalsSDK } from "./clmsr-sdk";
+export { WADAmount, USDCAmount, Quantity, Tick, MarketDistributionRaw, MarketRaw, Market, MarketDistribution, Position, mapMarket, mapDistribution, OpenCostResult, IncreaseCostResult, DecreaseProceedsResult, CloseProceedsResult, ClaimResult, QuantityFromCostResult, QuantityFromProceedsResult, PositionValueResult, FeeInfo, ValidationError, CalculationError, } from "./types";
+export * as MathUtils from "./utils/math";
+export { toWAD, toMicroUSDC } from "./clmsr-sdk";
+export { createCLMSRSDK, createSignalsSDK } from "./clmsr-sdk";
+export declare const VERSION = "1.0.0";

package/dist/index.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * Signals v1 SDK for TypeScript
+ *
+ * 컨트랙트 뷰함수들과 역함수 제공
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = exports.createSignalsSDK = exports.createCLMSRSDK = exports.toMicroUSDC = exports.toWAD = exports.MathUtils = exports.CalculationError = exports.ValidationError = exports.mapDistribution = exports.mapMarket = exports.SignalsSDK = exports.CLMSRSDK = void 0;
+// Export main SDK class
+var clmsr_sdk_1 = require("./clmsr-sdk");
+Object.defineProperty(exports, "CLMSRSDK", { enumerable: true, get: function () { return clmsr_sdk_1.CLMSRSDK; } });
+var clmsr_sdk_2 = require("./clmsr-sdk");
+Object.defineProperty(exports, "SignalsSDK", { enumerable: true, get: function () { return clmsr_sdk_2.CLMSRSDK; } });
+// Export types
+var types_1 = require("./types");
+// Data adapters
+Object.defineProperty(exports, "mapMarket", { enumerable: true, get: function () { return types_1.mapMarket; } });
+Object.defineProperty(exports, "mapDistribution", { enumerable: true, get: function () { return types_1.mapDistribution; } });
+// Errors
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return types_1.ValidationError; } });
+Object.defineProperty(exports, "CalculationError", { enumerable: true, get: function () { return types_1.CalculationError; } });
+// Export utility functions
+exports.MathUtils = __importStar(require("./utils/math"));
+// Convenience functions
+var clmsr_sdk_3 = require("./clmsr-sdk");
+Object.defineProperty(exports, "toWAD", { enumerable: true, get: function () { return clmsr_sdk_3.toWAD; } });
+Object.defineProperty(exports, "toMicroUSDC", { enumerable: true, get: function () { return clmsr_sdk_3.toMicroUSDC; } });
+var clmsr_sdk_4 = require("./clmsr-sdk");
+Object.defineProperty(exports, "createCLMSRSDK", { enumerable: true, get: function () { return clmsr_sdk_4.createCLMSRSDK; } });
+Object.defineProperty(exports, "createSignalsSDK", { enumerable: true, get: function () { return clmsr_sdk_4.createSignalsSDK; } });
+// Version (keep in sync with package.json)
+exports.VERSION = "1.0.0";

package/dist/types.d.ts

@@ -0,0 +1,161 @@
+import Big from "big.js";
+/** WAD format amount (18 decimals) */
+export type WADAmount = Big;
+/** USDC amount (6 decimals) */
+export type USDCAmount = Big;
+/** Trade quantity (also 6 decimals like USDC) */
+export type Quantity = Big;
+/** Tick value (int256) */
+export type Tick = number;
+/** Raw market distribution data from GraphQL (문자열 형태) */
+export interface MarketDistributionRaw {
+    totalSum: string;
+    binFactors: string[];
+    minFactor?: string;
+    maxFactor?: string;
+    avgFactor?: string;
+    totalVolume?: string;
+    binVolumes?: string[];
+    tickRanges?: string[];
+}
+/** Raw market data from GraphQL */
+export interface MarketRaw {
+    liquidityParameter: string;
+    minTick: number;
+    maxTick: number;
+    tickSpacing: number;
+    feePolicyDescriptor?: string;
+    isSettled?: boolean;
+    settlementValue?: string;
+    settlementTick?: number;
+}
+/** Market data for SDK calculations (숫자 객체만) */
+export interface Market {
+    liquidityParameter: WADAmount;
+    minTick: Tick;
+    maxTick: Tick;
+    tickSpacing: Tick;
+    feePolicyDescriptor?: string;
+    isSettled?: boolean;
+    settlementValue?: USDCAmount;
+    settlementTick?: Tick;
+}
+/** Market distribution data for SDK calculations (WAD 기반) */
+export interface MarketDistribution {
+    totalSum: WADAmount;
+    binFactors: WADAmount[];
+    minFactor?: WADAmount;
+    maxFactor?: WADAmount;
+    avgFactor?: WADAmount;
+    totalVolume?: USDCAmount;
+    binVolumes?: USDCAmount[];
+    tickRanges?: string[];
+}
+/** Position data */
+export interface Position {
+    lowerTick: Tick;
+    upperTick: Tick;
+    quantity: Quantity;
+}
+export declare const FeePolicyKind: {
+    readonly Null: "null";
+    readonly Percentage: "percentage";
+    readonly Custom: "custom";
+};
+export type FeePolicyKind = (typeof FeePolicyKind)[keyof typeof FeePolicyKind];
+interface BaseFeeInfo {
+    policy: FeePolicyKind;
+    descriptor?: string;
+    name?: string;
+}
+interface NullFeeInfo extends BaseFeeInfo {
+    policy: typeof FeePolicyKind.Null;
+}
+interface PercentageFeeInfo extends BaseFeeInfo {
+    policy: typeof FeePolicyKind.Percentage;
+    bps: Big;
+}
+interface CustomFeeInfo extends BaseFeeInfo {
+    policy: typeof FeePolicyKind.Custom;
+}
+export type FeeInfo = NullFeeInfo | PercentageFeeInfo | CustomFeeInfo;
+/**
+ * Convert raw GraphQL market data to SDK calculation format
+ * @param raw Raw market data from GraphQL
+ * @returns Market data for SDK calculations
+ */
+export declare function mapMarket(raw: MarketRaw): Market;
+/**
+ * Convert raw GraphQL distribution data to SDK calculation format
+ * @param raw Raw distribution data from GraphQL
+ * @returns Distribution data for SDK calculations
+ */
+export declare function mapDistribution(raw: MarketDistributionRaw): MarketDistribution;
+/** calculateOpenCost 결과 */
+export interface OpenCostResult {
+    cost: USDCAmount;
+    averagePrice: USDCAmount;
+    feeAmount: USDCAmount;
+    feeRate: Big;
+    feeInfo: FeeInfo;
+}
+/** calculateIncreaseCost 결과 */
+export interface IncreaseCostResult {
+    additionalCost: USDCAmount;
+    averagePrice: USDCAmount;
+    feeAmount: USDCAmount;
+    feeRate: Big;
+    feeInfo: FeeInfo;
+}
+/** calculateDecreaseProceeds 결과 */
+export interface DecreaseProceedsResult {
+    proceeds: USDCAmount;
+    averagePrice: USDCAmount;
+    feeAmount: USDCAmount;
+    feeRate: Big;
+    feeInfo: FeeInfo;
+}
+/** calculateCloseProceeds 결과 */
+export interface CloseProceedsResult {
+    proceeds: USDCAmount;
+    averagePrice: USDCAmount;
+    feeAmount: USDCAmount;
+    feeRate: Big;
+    feeInfo: FeeInfo;
+}
+/** calculateClaim 결과 */
+export interface ClaimResult {
+    payout: USDCAmount;
+}
+/** calculateQuantityFromCost 결과 */
+export interface QuantityFromCostResult {
+    quantity: Quantity;
+    actualCost: USDCAmount;
+    feeAmount: USDCAmount;
+    feeRate: Big;
+    feeInfo: FeeInfo;
+}
+/** calculateQuantityFromProceeds 결과 (매도용 역함수) */
+export interface QuantityFromProceedsResult {
+    quantity: Quantity;
+    actualProceeds: USDCAmount;
+    feeAmount: USDCAmount;
+    feeRate: Big;
+    feeInfo: FeeInfo;
+}
+/** calculatePositionValue 결과 (포지션 현재 가치 계산) */
+export interface PositionValueResult {
+    currentValue: USDCAmount;
+    unrealizedPnL: USDCAmount;
+    averagePrice: USDCAmount;
+    feeAmount: USDCAmount;
+    feeRate: Big;
+    feeInfo: FeeInfo;
+}
+export declare class ValidationError extends Error {
+    constructor(message: string);
+}
+export declare class CalculationError extends Error {
+    constructor(message: string);
+}
+export {};

package/dist/types.js

@@ -0,0 +1,83 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CalculationError = exports.ValidationError = exports.FeePolicyKind = void 0;
+exports.mapMarket = mapMarket;
+exports.mapDistribution = mapDistribution;
+const big_js_1 = __importDefault(require("big.js"));
+// ============================================================================
+// FEE DETAILS
+// ============================================================================
+exports.FeePolicyKind = {
+    Null: "null",
+    Percentage: "percentage",
+    Custom: "custom",
+};
+// ============================================================================
+// DATA ADAPTERS (GraphQL ↔ SDK 타입 변환)
+// ============================================================================
+/**
+ * Convert raw GraphQL market data to SDK calculation format
+ * @param raw Raw market data from GraphQL
+ * @returns Market data for SDK calculations
+ */
+function mapMarket(raw) {
+    return {
+        liquidityParameter: new big_js_1.default(raw.liquidityParameter),
+        minTick: raw.minTick,
+        maxTick: raw.maxTick,
+        tickSpacing: raw.tickSpacing,
+        ...(raw.feePolicyDescriptor !== undefined && {
+            feePolicyDescriptor: raw.feePolicyDescriptor,
+        }),
+        ...(raw.isSettled !== undefined && { isSettled: raw.isSettled }),
+        ...(raw.settlementValue !== undefined && {
+            settlementValue: new big_js_1.default(raw.settlementValue),
+        }),
+        ...(raw.settlementTick !== undefined && {
+            settlementTick: raw.settlementTick,
+        }),
+    };
+}
+/**
+ * Convert raw GraphQL distribution data to SDK calculation format
+ * @param raw Raw distribution data from GraphQL
+ * @returns Distribution data for SDK calculations
+ */
+function mapDistribution(raw) {
+    return {
+        // 필수 필드들
+        totalSum: new big_js_1.default(raw.totalSum),
+        binFactors: raw.binFactors.map((s) => new big_js_1.default(s)),
+        // 선택적 필드들 (정보성, 계산에 사용되지 않음)
+        ...(raw.minFactor !== undefined && { minFactor: new big_js_1.default(raw.minFactor) }),
+        ...(raw.maxFactor !== undefined && { maxFactor: new big_js_1.default(raw.maxFactor) }),
+        ...(raw.avgFactor !== undefined && { avgFactor: new big_js_1.default(raw.avgFactor) }),
+        ...(raw.totalVolume !== undefined && {
+            totalVolume: new big_js_1.default(raw.totalVolume),
+        }),
+        ...(raw.binVolumes !== undefined && {
+            binVolumes: raw.binVolumes.map((s) => new big_js_1.default(s)),
+        }),
+        ...(raw.tickRanges !== undefined && { tickRanges: raw.tickRanges }),
+    };
+}
+// ============================================================================
+// ERRORS
+// ============================================================================
+class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ValidationError";
+    }
+}
+exports.ValidationError = ValidationError;
+class CalculationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CalculationError";
+    }
+}
+exports.CalculationError = CalculationError;