@acta-markets/ts-sdk 0.0.12-beta → 0.0.13-beta

package/dist/cjs/ws/index.js

@@ -21,3 +21,4 @@ __exportStar(require("./flows"), exports);
 __exportStar(require("./sponsoredTx"), exports);
 __exportStar(require("./apy"), exports);
 __exportStar(require("./discovery"), exports);
+__exportStar(require("./sizing"), exports);

package/dist/cjs/ws/sizing.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * CSP quantity / size-rule conversion helpers.
+ *
+ * On the wire, `quantity` is always in underlying atomic units (e.g. SOL lamports).
+ * For covered calls the user thinks in underlying (SOL), so no conversion is needed.
+ * For cash-secured puts the user thinks in quote (USDC), so the frontend must convert
+ * between the user's USDC input and the wire's underlying quantity.
+ *
+ * These helpers handle that conversion and let the frontend display size_rule
+ * constraints in quote terms.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.quoteAmountToQuantity = quoteAmountToQuantity;
+exports.quantityToQuoteAmount = quantityToQuoteAmount;
+exports.sizeRuleInQuoteTerms = sizeRuleInQuoteTerms;
+const apy_1 = require("./apy");
+/**
+ * Convert a user's quote-denominated deposit (e.g. 450 USDC) to the wire
+ * quantity in underlying atomic units.
+ *
+ * Formula: `round(quoteAmount * 10^underlyingDecimals * PRICE_SCALE / strike1e9)`
+ *
+ * @param quoteAmount     Human-readable quote amount (e.g. 450 for "450 USDC")
+ * @param strike1e9       Strike price, 1e9-scaled (e.g. 90_000_000_000 for $90)
+ * @param underlyingDecimals  Decimals of the underlying mint (e.g. 9 for SOL)
+ * @returns Wire quantity (underlying atomic units)
+ */
+function quoteAmountToQuantity(quoteAmount, strike1e9, underlyingDecimals) {
+    if (!Number.isFinite(quoteAmount) || quoteAmount < 0) {
+        throw new Error("quoteAmount must be a non-negative finite number");
+    }
+    if (!Number.isFinite(strike1e9) || strike1e9 <= 0) {
+        throw new Error("strike1e9 must be a positive finite number");
+    }
+    const atomicFactor = Math.pow(10, underlyingDecimals);
+    return Math.round(quoteAmount * atomicFactor * apy_1.PRICE_SCALE / strike1e9);
+}
+/**
+ * Convert a wire quantity (underlying atomic units) to a human-readable
+ * quote-denominated amount.
+ *
+ * Formula: `quantity * strike1e9 / PRICE_SCALE / 10^underlyingDecimals`
+ *
+ * @param quantity            Wire quantity (underlying atomic units)
+ * @param strike1e9           Strike price, 1e9-scaled
+ * @param underlyingDecimals  Decimals of the underlying mint
+ * @returns Human-readable quote amount (e.g. 450 for "450 USDC")
+ */
+function quantityToQuoteAmount(quantity, strike1e9, underlyingDecimals) {
+    if (!Number.isFinite(quantity) || quantity < 0) {
+        throw new Error("quantity must be a non-negative finite number");
+    }
+    if (!Number.isFinite(strike1e9) || strike1e9 <= 0) {
+        throw new Error("strike1e9 must be a positive finite number");
+    }
+    const atomicFactor = Math.pow(10, underlyingDecimals);
+    return quantity * strike1e9 / apy_1.PRICE_SCALE / atomicFactor;
+}
+/**
+ * Convert a size_rule (underlying atomic units) to human-readable quote terms.
+ *
+ * Example: SOL/USDC CSP, strike $90, rule {min: 1e9, max: 10e9, step: 1e8}
+ * → returns {min: 90, max: 900, step: 9} (USDC)
+ *
+ * @param rule                Size rule from MarketDescriptorInfo
+ * @param strike1e9           Strike price, 1e9-scaled
+ * @param underlyingDecimals  Decimals of the underlying mint
+ */
+function sizeRuleInQuoteTerms(rule, strike1e9, underlyingDecimals) {
+    if (!Number.isFinite(strike1e9) || strike1e9 <= 0) {
+        throw new Error("strike1e9 must be a positive finite number");
+    }
+    return {
+        min: quantityToQuoteAmount(rule.min_size, strike1e9, underlyingDecimals),
+        max: quantityToQuoteAmount(rule.max_size, strike1e9, underlyingDecimals),
+        step: quantityToQuoteAmount(rule.step, strike1e9, underlyingDecimals),
+    };
+}

package/dist/cjs/ws/sizing.test.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const sizing_1 = require("./sizing");
+describe("ws sizing helpers", () => {
+    // SOL: 9 decimals, strike $90 = 90_000_000_000 (1e9-scaled)
+    const SOL_DECIMALS = 9;
+    const STRIKE_90 = 90_000_000_000;
+    describe("quoteAmountToQuantity", () => {
+        it("converts 450 USDC at $90 strike to 5 SOL in lamports", () => {
+            expect((0, sizing_1.quoteAmountToQuantity)(450, STRIKE_90, SOL_DECIMALS)).toBe(5_000_000_000);
+        });
+        it("converts 90 USDC (min) to 1 SOL in lamports", () => {
+            expect((0, sizing_1.quoteAmountToQuantity)(90, STRIKE_90, SOL_DECIMALS)).toBe(1_000_000_000);
+        });
+        it("converts 9 USDC (one step) to 0.1 SOL in lamports", () => {
+            expect((0, sizing_1.quoteAmountToQuantity)(9, STRIKE_90, SOL_DECIMALS)).toBe(100_000_000);
+        });
+        it("returns 0 for 0 input", () => {
+            expect((0, sizing_1.quoteAmountToQuantity)(0, STRIKE_90, SOL_DECIMALS)).toBe(0);
+        });
+        it("throws on negative quoteAmount", () => {
+            expect(() => (0, sizing_1.quoteAmountToQuantity)(-1, STRIKE_90, SOL_DECIMALS)).toThrow("quoteAmount");
+        });
+        it("throws on zero strike", () => {
+            expect(() => (0, sizing_1.quoteAmountToQuantity)(100, 0, SOL_DECIMALS)).toThrow("strike1e9");
+        });
+        it("throws on negative strike", () => {
+            expect(() => (0, sizing_1.quoteAmountToQuantity)(100, -1, SOL_DECIMALS)).toThrow("strike1e9");
+        });
+    });
+    describe("quantityToQuoteAmount", () => {
+        it("converts 5 SOL lamports at $90 strike to 450 USDC", () => {
+            expect((0, sizing_1.quantityToQuoteAmount)(5_000_000_000, STRIKE_90, SOL_DECIMALS)).toBeCloseTo(450, 10);
+        });
+        it("converts 1 SOL lamports to 90 USDC", () => {
+            expect((0, sizing_1.quantityToQuoteAmount)(1_000_000_000, STRIKE_90, SOL_DECIMALS)).toBeCloseTo(90, 10);
+        });
+        it("converts 0.1 SOL lamports to 9 USDC", () => {
+            expect((0, sizing_1.quantityToQuoteAmount)(100_000_000, STRIKE_90, SOL_DECIMALS)).toBeCloseTo(9, 10);
+        });
+        it("returns 0 for 0 quantity", () => {
+            expect((0, sizing_1.quantityToQuoteAmount)(0, STRIKE_90, SOL_DECIMALS)).toBe(0);
+        });
+        it("throws on negative quantity", () => {
+            expect(() => (0, sizing_1.quantityToQuoteAmount)(-1, STRIKE_90, SOL_DECIMALS)).toThrow("quantity");
+        });
+    });
+    describe("round-trip", () => {
+        it("quoteAmount -> quantity -> quoteAmount is stable", () => {
+            const original = 450;
+            const quantity = (0, sizing_1.quoteAmountToQuantity)(original, STRIKE_90, SOL_DECIMALS);
+            const restored = (0, sizing_1.quantityToQuoteAmount)(quantity, STRIKE_90, SOL_DECIMALS);
+            expect(restored).toBeCloseTo(original, 6);
+        });
+        it("round-trips at step granularity (9 USDC)", () => {
+            const original = 9;
+            const quantity = (0, sizing_1.quoteAmountToQuantity)(original, STRIKE_90, SOL_DECIMALS);
+            const restored = (0, sizing_1.quantityToQuoteAmount)(quantity, STRIKE_90, SOL_DECIMALS);
+            expect(restored).toBeCloseTo(original, 6);
+        });
+        it("round-trips with different strike ($150)", () => {
+            const strike150 = 150_000_000_000;
+            const original = 300;
+            const quantity = (0, sizing_1.quoteAmountToQuantity)(original, strike150, SOL_DECIMALS);
+            expect(quantity).toBe(2_000_000_000); // 2 SOL
+            const restored = (0, sizing_1.quantityToQuoteAmount)(quantity, strike150, SOL_DECIMALS);
+            expect(restored).toBeCloseTo(original, 6);
+        });
+    });
+    describe("sizeRuleInQuoteTerms", () => {
+        const rule = { min_size: 1_000_000_000, max_size: 10_000_000_000, step: 100_000_000 };
+        it("converts SOL size_rule to USDC terms at $90 strike", () => {
+            const result = (0, sizing_1.sizeRuleInQuoteTerms)(rule, STRIKE_90, SOL_DECIMALS);
+            expect(result.min).toBeCloseTo(90, 6);
+            expect(result.max).toBeCloseTo(900, 6);
+            expect(result.step).toBeCloseTo(9, 6);
+        });
+        it("converts at $150 strike", () => {
+            const strike150 = 150_000_000_000;
+            const result = (0, sizing_1.sizeRuleInQuoteTerms)(rule, strike150, SOL_DECIMALS);
+            expect(result.min).toBeCloseTo(150, 6);
+            expect(result.max).toBeCloseTo(1500, 6);
+            expect(result.step).toBeCloseTo(15, 6);
+        });
+        it("throws on zero strike", () => {
+            expect(() => (0, sizing_1.sizeRuleInQuoteTerms)(rule, 0, SOL_DECIMALS)).toThrow("strike1e9");
+        });
+    });
+    describe("non-9-decimal underlying", () => {
+        // ETH: 8 decimals
+        const ETH_DECIMALS = 8;
+        const STRIKE_3000 = 3_000_000_000_000; // $3000
+        it("converts 6000 USDC at $3000 strike to 2 ETH (8 decimals)", () => {
+            expect((0, sizing_1.quoteAmountToQuantity)(6000, STRIKE_3000, ETH_DECIMALS)).toBe(200_000_000);
+        });
+        it("converts 2 ETH back to 6000 USDC", () => {
+            expect((0, sizing_1.quantityToQuoteAmount)(200_000_000, STRIKE_3000, ETH_DECIMALS)).toBeCloseTo(6000, 6);
+        });
+    });
+});

package/dist/ws/index.d.ts

@@ -5,3 +5,4 @@ export * from "./flows";
 export * from "./sponsoredTx";
 export * from "./apy";
 export * from "./discovery";
+export * from "./sizing";

package/dist/ws/index.js

@@ -5,3 +5,4 @@ export * from "./flows";
 export * from "./sponsoredTx";
 export * from "./apy";
 export * from "./discovery";
+export * from "./sizing";

package/dist/ws/sizing.d.ts

@@ -0,0 +1,52 @@
+/**
+ * CSP quantity / size-rule conversion helpers.
+ *
+ * On the wire, `quantity` is always in underlying atomic units (e.g. SOL lamports).
+ * For covered calls the user thinks in underlying (SOL), so no conversion is needed.
+ * For cash-secured puts the user thinks in quote (USDC), so the frontend must convert
+ * between the user's USDC input and the wire's underlying quantity.
+ *
+ * These helpers handle that conversion and let the frontend display size_rule
+ * constraints in quote terms.
+ */
+import type { QuantitySizeRuleLike } from "./wirePolicy";
+/**
+ * Convert a user's quote-denominated deposit (e.g. 450 USDC) to the wire
+ * quantity in underlying atomic units.
+ *
+ * Formula: `round(quoteAmount * 10^underlyingDecimals * PRICE_SCALE / strike1e9)`
+ *
+ * @param quoteAmount     Human-readable quote amount (e.g. 450 for "450 USDC")
+ * @param strike1e9       Strike price, 1e9-scaled (e.g. 90_000_000_000 for $90)
+ * @param underlyingDecimals  Decimals of the underlying mint (e.g. 9 for SOL)
+ * @returns Wire quantity (underlying atomic units)
+ */
+export declare function quoteAmountToQuantity(quoteAmount: number, strike1e9: number, underlyingDecimals: number): number;
+/**
+ * Convert a wire quantity (underlying atomic units) to a human-readable
+ * quote-denominated amount.
+ *
+ * Formula: `quantity * strike1e9 / PRICE_SCALE / 10^underlyingDecimals`
+ *
+ * @param quantity            Wire quantity (underlying atomic units)
+ * @param strike1e9           Strike price, 1e9-scaled
+ * @param underlyingDecimals  Decimals of the underlying mint
+ * @returns Human-readable quote amount (e.g. 450 for "450 USDC")
+ */
+export declare function quantityToQuoteAmount(quantity: number, strike1e9: number, underlyingDecimals: number): number;
+export type QuoteDenominatedSizeRule = {
+    min: number;
+    max: number;
+    step: number;
+};
+/**
+ * Convert a size_rule (underlying atomic units) to human-readable quote terms.
+ *
+ * Example: SOL/USDC CSP, strike $90, rule {min: 1e9, max: 10e9, step: 1e8}
+ * → returns {min: 90, max: 900, step: 9} (USDC)
+ *
+ * @param rule                Size rule from MarketDescriptorInfo
+ * @param strike1e9           Strike price, 1e9-scaled
+ * @param underlyingDecimals  Decimals of the underlying mint
+ */
+export declare function sizeRuleInQuoteTerms(rule: QuantitySizeRuleLike, strike1e9: number, underlyingDecimals: number): QuoteDenominatedSizeRule;

package/dist/ws/sizing.js

@@ -0,0 +1,74 @@
+/**
+ * CSP quantity / size-rule conversion helpers.
+ *
+ * On the wire, `quantity` is always in underlying atomic units (e.g. SOL lamports).
+ * For covered calls the user thinks in underlying (SOL), so no conversion is needed.
+ * For cash-secured puts the user thinks in quote (USDC), so the frontend must convert
+ * between the user's USDC input and the wire's underlying quantity.
+ *
+ * These helpers handle that conversion and let the frontend display size_rule
+ * constraints in quote terms.
+ */
+import { PRICE_SCALE } from "./apy";
+/**
+ * Convert a user's quote-denominated deposit (e.g. 450 USDC) to the wire
+ * quantity in underlying atomic units.
+ *
+ * Formula: `round(quoteAmount * 10^underlyingDecimals * PRICE_SCALE / strike1e9)`
+ *
+ * @param quoteAmount     Human-readable quote amount (e.g. 450 for "450 USDC")
+ * @param strike1e9       Strike price, 1e9-scaled (e.g. 90_000_000_000 for $90)
+ * @param underlyingDecimals  Decimals of the underlying mint (e.g. 9 for SOL)
+ * @returns Wire quantity (underlying atomic units)
+ */
+export function quoteAmountToQuantity(quoteAmount, strike1e9, underlyingDecimals) {
+    if (!Number.isFinite(quoteAmount) || quoteAmount < 0) {
+        throw new Error("quoteAmount must be a non-negative finite number");
+    }
+    if (!Number.isFinite(strike1e9) || strike1e9 <= 0) {
+        throw new Error("strike1e9 must be a positive finite number");
+    }
+    const atomicFactor = Math.pow(10, underlyingDecimals);
+    return Math.round(quoteAmount * atomicFactor * PRICE_SCALE / strike1e9);
+}
+/**
+ * Convert a wire quantity (underlying atomic units) to a human-readable
+ * quote-denominated amount.
+ *
+ * Formula: `quantity * strike1e9 / PRICE_SCALE / 10^underlyingDecimals`
+ *
+ * @param quantity            Wire quantity (underlying atomic units)
+ * @param strike1e9           Strike price, 1e9-scaled
+ * @param underlyingDecimals  Decimals of the underlying mint
+ * @returns Human-readable quote amount (e.g. 450 for "450 USDC")
+ */
+export function quantityToQuoteAmount(quantity, strike1e9, underlyingDecimals) {
+    if (!Number.isFinite(quantity) || quantity < 0) {
+        throw new Error("quantity must be a non-negative finite number");
+    }
+    if (!Number.isFinite(strike1e9) || strike1e9 <= 0) {
+        throw new Error("strike1e9 must be a positive finite number");
+    }
+    const atomicFactor = Math.pow(10, underlyingDecimals);
+    return quantity * strike1e9 / PRICE_SCALE / atomicFactor;
+}
+/**
+ * Convert a size_rule (underlying atomic units) to human-readable quote terms.
+ *
+ * Example: SOL/USDC CSP, strike $90, rule {min: 1e9, max: 10e9, step: 1e8}
+ * → returns {min: 90, max: 900, step: 9} (USDC)
+ *
+ * @param rule                Size rule from MarketDescriptorInfo
+ * @param strike1e9           Strike price, 1e9-scaled
+ * @param underlyingDecimals  Decimals of the underlying mint
+ */
+export function sizeRuleInQuoteTerms(rule, strike1e9, underlyingDecimals) {
+    if (!Number.isFinite(strike1e9) || strike1e9 <= 0) {
+        throw new Error("strike1e9 must be a positive finite number");
+    }
+    return {
+        min: quantityToQuoteAmount(rule.min_size, strike1e9, underlyingDecimals),
+        max: quantityToQuoteAmount(rule.max_size, strike1e9, underlyingDecimals),
+        step: quantityToQuoteAmount(rule.step, strike1e9, underlyingDecimals),
+    };
+}

package/dist/ws/sizing.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ws/sizing.test.js

@@ -0,0 +1,98 @@
+import { quoteAmountToQuantity, quantityToQuoteAmount, sizeRuleInQuoteTerms, } from "./sizing";
+describe("ws sizing helpers", () => {
+    // SOL: 9 decimals, strike $90 = 90_000_000_000 (1e9-scaled)
+    const SOL_DECIMALS = 9;
+    const STRIKE_90 = 90_000_000_000;
+    describe("quoteAmountToQuantity", () => {
+        it("converts 450 USDC at $90 strike to 5 SOL in lamports", () => {
+            expect(quoteAmountToQuantity(450, STRIKE_90, SOL_DECIMALS)).toBe(5_000_000_000);
+        });
+        it("converts 90 USDC (min) to 1 SOL in lamports", () => {
+            expect(quoteAmountToQuantity(90, STRIKE_90, SOL_DECIMALS)).toBe(1_000_000_000);
+        });
+        it("converts 9 USDC (one step) to 0.1 SOL in lamports", () => {
+            expect(quoteAmountToQuantity(9, STRIKE_90, SOL_DECIMALS)).toBe(100_000_000);
+        });
+        it("returns 0 for 0 input", () => {
+            expect(quoteAmountToQuantity(0, STRIKE_90, SOL_DECIMALS)).toBe(0);
+        });
+        it("throws on negative quoteAmount", () => {
+            expect(() => quoteAmountToQuantity(-1, STRIKE_90, SOL_DECIMALS)).toThrow("quoteAmount");
+        });
+        it("throws on zero strike", () => {
+            expect(() => quoteAmountToQuantity(100, 0, SOL_DECIMALS)).toThrow("strike1e9");
+        });
+        it("throws on negative strike", () => {
+            expect(() => quoteAmountToQuantity(100, -1, SOL_DECIMALS)).toThrow("strike1e9");
+        });
+    });
+    describe("quantityToQuoteAmount", () => {
+        it("converts 5 SOL lamports at $90 strike to 450 USDC", () => {
+            expect(quantityToQuoteAmount(5_000_000_000, STRIKE_90, SOL_DECIMALS)).toBeCloseTo(450, 10);
+        });
+        it("converts 1 SOL lamports to 90 USDC", () => {
+            expect(quantityToQuoteAmount(1_000_000_000, STRIKE_90, SOL_DECIMALS)).toBeCloseTo(90, 10);
+        });
+        it("converts 0.1 SOL lamports to 9 USDC", () => {
+            expect(quantityToQuoteAmount(100_000_000, STRIKE_90, SOL_DECIMALS)).toBeCloseTo(9, 10);
+        });
+        it("returns 0 for 0 quantity", () => {
+            expect(quantityToQuoteAmount(0, STRIKE_90, SOL_DECIMALS)).toBe(0);
+        });
+        it("throws on negative quantity", () => {
+            expect(() => quantityToQuoteAmount(-1, STRIKE_90, SOL_DECIMALS)).toThrow("quantity");
+        });
+    });
+    describe("round-trip", () => {
+        it("quoteAmount -> quantity -> quoteAmount is stable", () => {
+            const original = 450;
+            const quantity = quoteAmountToQuantity(original, STRIKE_90, SOL_DECIMALS);
+            const restored = quantityToQuoteAmount(quantity, STRIKE_90, SOL_DECIMALS);
+            expect(restored).toBeCloseTo(original, 6);
+        });
+        it("round-trips at step granularity (9 USDC)", () => {
+            const original = 9;
+            const quantity = quoteAmountToQuantity(original, STRIKE_90, SOL_DECIMALS);
+            const restored = quantityToQuoteAmount(quantity, STRIKE_90, SOL_DECIMALS);
+            expect(restored).toBeCloseTo(original, 6);
+        });
+        it("round-trips with different strike ($150)", () => {
+            const strike150 = 150_000_000_000;
+            const original = 300;
+            const quantity = quoteAmountToQuantity(original, strike150, SOL_DECIMALS);
+            expect(quantity).toBe(2_000_000_000); // 2 SOL
+            const restored = quantityToQuoteAmount(quantity, strike150, SOL_DECIMALS);
+            expect(restored).toBeCloseTo(original, 6);
+        });
+    });
+    describe("sizeRuleInQuoteTerms", () => {
+        const rule = { min_size: 1_000_000_000, max_size: 10_000_000_000, step: 100_000_000 };
+        it("converts SOL size_rule to USDC terms at $90 strike", () => {
+            const result = sizeRuleInQuoteTerms(rule, STRIKE_90, SOL_DECIMALS);
+            expect(result.min).toBeCloseTo(90, 6);
+            expect(result.max).toBeCloseTo(900, 6);
+            expect(result.step).toBeCloseTo(9, 6);
+        });
+        it("converts at $150 strike", () => {
+            const strike150 = 150_000_000_000;
+            const result = sizeRuleInQuoteTerms(rule, strike150, SOL_DECIMALS);
+            expect(result.min).toBeCloseTo(150, 6);
+            expect(result.max).toBeCloseTo(1500, 6);
+            expect(result.step).toBeCloseTo(15, 6);
+        });
+        it("throws on zero strike", () => {
+            expect(() => sizeRuleInQuoteTerms(rule, 0, SOL_DECIMALS)).toThrow("strike1e9");
+        });
+    });
+    describe("non-9-decimal underlying", () => {
+        // ETH: 8 decimals
+        const ETH_DECIMALS = 8;
+        const STRIKE_3000 = 3_000_000_000_000; // $3000
+        it("converts 6000 USDC at $3000 strike to 2 ETH (8 decimals)", () => {
+            expect(quoteAmountToQuantity(6000, STRIKE_3000, ETH_DECIMALS)).toBe(200_000_000);
+        });
+        it("converts 2 ETH back to 6000 USDC", () => {
+            expect(quantityToQuoteAmount(200_000_000, STRIKE_3000, ETH_DECIMALS)).toBeCloseTo(6000, 6);
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acta-markets/ts-sdk",
-  "version": "0.0.12-beta",
+  "version": "0.0.13-beta",
   "description": "TypeScript SDK for Acta Protocol",
   "type": "module",
   "main": "dist/index.js",