lovewebconnection 0.0.0-stage → 0.2.0

package/dist/market.d.ts

@@ -0,0 +1,323 @@
+/**
+ * A fixed-price market: every swap settles at one price that never moves, so a
+ * trade can never reprice (devalue) the token. The pool's job is settlement, not
+ * price discovery.
+ *
+ * A constant-product AMM needs `k` worth of reserves to absorb a trade, so a
+ * $1 pool answers a $1 trade and dies. Here the price is a fixed rational, the
+ * pool holds inventory at that price, and a buy is reversed exactly by a sell of
+ * the same size: the reserves return to where they started, minus nothing but
+ * the fee. Cumulative volume is therefore bounded by swap count, not by the
+ * dollars deposited — a $1 pool that is traded round trip a billion times has
+ * settled a billion dollars' worth of volume while its reserves never moved.
+ *
+ * The one honest limit is net directional flow: a buy the pool cannot fill from
+ * its base inventory, or a sell it cannot pay from its quote inventory, is
+ * refused with a reason instead of being silently repriced.
+ */
+/** Which leg the trader sends: `buy` sends quote for base, `sell` sends base for quote. */
+export type MarketSide = "buy" | "sell";
+export type MarketErrorCode = "invalid-amount" | "insufficient-liquidity" | "insufficient-shares" | "invalid-pool";
+export declare class MarketError extends Error {
+    readonly code: MarketErrorCode;
+    constructor(code: MarketErrorCode, message: string);
+}
+export declare class MarketArgError extends Error {
+    constructor(message: string);
+}
+/** Why a quote cannot be executed, or `null` when it can. */
+export type MarketIssue = "amount-too-small" | "insufficient-liquidity" | null;
+export interface MarketConfig {
+    baseSymbol: string;
+    quoteSymbol: string;
+    baseDecimals: number;
+    quoteDecimals: number;
+    /** Fixed price as a reduced rational: quote base units per base base unit. */
+    priceNum: bigint;
+    priceDen: bigint;
+    /** Fee taken from the input leg and left in the pool for liquidity providers. */
+    feeBps: number;
+}
+export interface ReservePair {
+    base: bigint;
+    quote: bigint;
+}
+export interface SwapQuote {
+    side: MarketSide;
+    /** What the trader sends, in that token's base units. */
+    amountIn: bigint;
+    /** What the trader receives, in the other token's base units. */
+    amountOut: bigint;
+    /** Fee taken from `amountIn`, left in the pool. */
+    fee: bigint;
+    /** Notional value of the trade in quote base units. */
+    notional: bigint;
+    /** Reserves the pool holds if this quote is executed. */
+    reservesAfter: ReservePair;
+    /** Always zero: a fixed-price fill cannot move the price. */
+    priceImpactBps: 0;
+    executable: boolean;
+    issue: MarketIssue;
+    /** Human-readable reason when `executable` is false. */
+    reason: string | null;
+}
+export interface LiquidityReceipt {
+    kind: "add" | "remove";
+    base: bigint;
+    quote: bigint;
+    shares: bigint;
+    sharesAfter: bigint;
+    liquidityValueQuote: bigint;
+}
+export interface MarketState {
+    baseSymbol: string;
+    quoteSymbol: string;
+    baseDecimals: number;
+    quoteDecimals: number;
+    priceNum: bigint;
+    priceDen: bigint;
+    /** The fixed price as a decimal string, quote per one whole base token. */
+    price: string;
+    feeBps: number;
+    baseReserve: bigint;
+    quoteReserve: bigint;
+    /** Value of both reserves at the fixed price, in quote base units. */
+    liquidityValueQuote: bigint;
+    shares: bigint;
+    /** Cumulative traded notional in quote base units. */
+    volumeQuote: bigint;
+    swaps: number;
+    /** Volume settled per unit of deposited liquidity — the turnover multiple. */
+    turnover: number;
+    /** Inventory drift from the opening reserves: the market's net exposure. */
+    netBase: bigint;
+    netQuote: bigint;
+}
+export interface MarketCapacity {
+    /** Most base one buy can take out right now. */
+    maxBuyBase: bigint;
+    /** Most base one sell can hand in right now, before quote reserves run out. */
+    maxSellBase: bigint;
+    /** Quote the pool can pay out in total. */
+    payQuote: bigint;
+    /** Value of the pool at the fixed price. */
+    liquidityValueQuote: bigint;
+}
+/** Where `lwc market --serve` listens unless told otherwise. */
+export declare const DEFAULT_MARKET_HOST = "127.0.0.1";
+export declare const DEFAULT_MARKET_PORT = 8787;
+export declare const MAX_MARKET_PORT = 65535;
+/** Requests per minute one client may make unless `--rate-limit` says otherwise. */
+export declare const DEFAULT_MARKET_RATE_LIMIT = 120;
+/** Render a rational as a decimal string, without trailing zeros. */
+export declare function rationalToDecimal(num: bigint, den: bigint, maxDecimals?: number): string;
+/**
+ * Turn a human price into the pool's rational. `"28.842"` with 8 base decimals
+ * and 6 quote decimals means one whole base token is worth 28.842 quote tokens,
+ * and the rational is expressed in raw units of each token.
+ */
+export declare function fixedPrice(human: string, baseDecimals: number, quoteDecimals: number): {
+    num: bigint;
+    den: bigint;
+};
+/** Share counts are whole units, so they never take decimals. */
+export declare function parseShares(value: string): bigint;
+/** Human price of a rational, quote per one whole base token. */
+export declare function humanPrice(num: bigint, den: bigint, baseDecimals: number, quoteDecimals: number): string;
+/** A decimal amount as base units, with the pool's own decimals. */
+export declare function parseMarketAmount(value: string, decimals: number, label: string): bigint;
+/** Base units as a trimmed decimal string. */
+export declare function formatMarketAmount(value: bigint, decimals: number): string;
+/** The on-disk shape, with every bigint written as a decimal string. */
+export interface MarketPoolJson {
+    version: 1;
+    baseSymbol: string;
+    quoteSymbol: string;
+    baseDecimals: number;
+    quoteDecimals: number;
+    priceNum: string;
+    priceDen: string;
+    feeBps: number;
+    baseReserve: string;
+    quoteReserve: string;
+    shares: string;
+    volumeQuote: string;
+    swaps: number;
+    openedBase: string;
+    openedQuote: string;
+}
+/** Convert a parsed pool file into runtime state, validating every field. */
+export declare function poolFromJson(raw: unknown): MarketPool;
+/** Read a pool file from disk, validating every field. */
+export declare function loadPoolFile(path: string): MarketPool;
+/** Write a pool file atomically, refusing to replace one without `force`. */
+export declare function savePoolFile(path: string, pool: MarketPool, options?: {
+    force?: boolean;
+}): MarketPoolJson;
+export interface MarketPoolState {
+    baseReserve: bigint;
+    quoteReserve: bigint;
+    shares: bigint;
+    volumeQuote: bigint;
+    swaps: number;
+    openedBase: bigint;
+    openedQuote: bigint;
+}
+/**
+ * A fixed-price settlement pool. Reserves only move when flow is net
+ * directional, so matched volume costs the pool nothing.
+ */
+export declare class MarketPool {
+    readonly config: MarketConfig;
+    private baseReserve;
+    private quoteReserve;
+    private sharesOut;
+    private volumeQuote;
+    private swapCount;
+    private readonly openedBase;
+    private readonly openedQuote;
+    constructor(config: MarketConfig, state?: Partial<MarketPoolState>);
+    /**
+     * Create a pool worth `liquidity` of the quote token, split evenly between the
+     * two legs at the fixed price, so one dollar on deposit really is one dollar.
+     */
+    static create(config: MarketConfig, liquidity: bigint): MarketPool;
+    /** Price of the base token in quote units, in raw units of each token. */
+    private get ratio();
+    /** Quote base units for a given base amount, at the fixed price (rounded down). */
+    quoteForBase(baseAmount: bigint): bigint;
+    /** Base units for a given quote amount, at the fixed price (rounded down). */
+    baseForQuote(quoteAmount: bigint): bigint;
+    /** Value of both reserves at the fixed price, in quote base units. */
+    liquidityValueQuote(): bigint;
+    /**
+     * Price a trade without touching the pool. A well-formed amount always gets a
+     * quote; `executable` and `reason` say whether the pool can settle it.
+     */
+    quote(side: MarketSide, amountIn: bigint): SwapQuote;
+    /** Execute a trade at the fixed price and return the fill. */
+    swap(side: MarketSide, amountIn: bigint): SwapQuote;
+    /** Deposit one or both legs and mint shares at the pre-deposit value. */
+    addLiquidity(input: Partial<ReservePair>): LiquidityReceipt;
+    /** Burn shares for their pro-rata slice of both reserves. */
+    removeLiquidity(shares: bigint): LiquidityReceipt;
+    /** What the pool can settle right now, and how much volume its liquidity backs. */
+    capacity(): MarketCapacity;
+    /** What the pool could settle right after `quote`, without applying it. */
+    capacityAfter(quote: SwapQuote): MarketCapacity;
+    state(): MarketState;
+    toJson(): MarketPoolJson;
+    private outSymbol;
+    private describe;
+}
+/** JSON form of a market state, with bigints as decimal strings. */
+export declare function toMarketJson(state: MarketState, path?: string | null): {
+    pool: string | null;
+    base: {
+        symbol: string;
+        decimals: number;
+        reserve: string;
+    };
+    quote: {
+        symbol: string;
+        decimals: number;
+        reserve: string;
+    };
+    price: {
+        value: string;
+        num: string;
+        den: string;
+        fixed: boolean;
+        priceImpactBps: number;
+    };
+    feeBps: number;
+    liquidity: {
+        valueQuote: string;
+        shares: string;
+    };
+    volume: {
+        quote: string;
+        swaps: number;
+        turnover: number;
+    };
+    netFlow: {
+        base: string;
+        quote: string;
+    };
+};
+/** JSON form of a swap quote, with bigints as decimal strings. */
+export declare function toSwapQuoteJson(quote: SwapQuote, state: MarketState): {
+    side: MarketSide;
+    amountIn: string;
+    amountOut: string;
+    fee: string;
+    notional: string;
+    inSymbol: string;
+    outSymbol: string;
+    price: string;
+    priceImpactBps: 0;
+    executable: boolean;
+    issue: MarketIssue;
+    reason: string | null;
+    reservesAfter: {
+        base: string;
+        quote: string;
+    };
+};
+/** Human report for `lwc market`. */
+export declare function formatMarketState(state: MarketState, path: string | null): string;
+/** Human report for one fill or quote. */
+export declare function formatSwapQuote(quote: SwapQuote, state: MarketState, options?: {
+    applied?: boolean;
+}): string;
+/** Human report for a liquidity deposit or withdrawal. */
+export declare function formatLiquidity(receipt: LiquidityReceipt, state: MarketState): string;
+/** Shortest access key `--api-key` accepts before the API is exposed. */
+export declare const MIN_MARKET_KEY_LENGTH = 8;
+export interface MarketServeOptions {
+    host: string;
+    port: number;
+    /** Browser origins allowed to call the API, or `["*"]` for any. */
+    corsOrigins: string[];
+    /** Key every pool route requires; null leaves the API open. */
+    accessKey: string | null;
+    /** Requests per minute one client may make; 0 turns the limiter off. */
+    rateLimitPerMinute?: number;
+    /**
+     * Where the per-client counters are kept between runs. Defaults to a file
+     * beside the pool; null keeps them in memory only.
+     */
+    limitsPath?: string | null;
+}
+export type MarketOperation = {
+    kind: "state";
+} | {
+    kind: "swap";
+    side: MarketSide;
+    amount: string;
+} | {
+    kind: "add";
+    quote: string | null;
+    base: string | null;
+    remove: string;
+};
+export interface MarketArgs {
+    poolPath: string;
+    init: {
+        price: string;
+        baseSymbol: string;
+        quoteSymbol: string;
+        baseDecimals: number;
+        quoteDecimals: number;
+        feeBps: number;
+        seed: string;
+    } | null;
+    /** The single operation this run performs, after any init. */
+    operation: MarketOperation;
+    force: boolean;
+    /** Price the trade without applying it. */
+    dryRun: boolean;
+    /** Serve the pool over HTTP instead of running one operation. */
+    serve: MarketServeOptions | null;
+}
+export declare function parseMarketArgs(argv: string[]): MarketArgs;