@moon-cx/sdk 0.0.0-stage → 2.0.1

package/dist/math/clmm-swap.js

@@ -0,0 +1,277 @@
+import { LimitExceededError } from "../core/errors.js";
+import { MAX_BINS_PER_SWAP, binBounds, sqrtPriceAtBin, sqrtPriceEnteringBin } from "./clmm.js";
+import { SCALE, q128DivCeil, q128DivFloor, q128Mul, q128MulCeil, q128MulFloor, q128Sqrt, mulDivCeil, mulDivFloor, } from "./q128.js";
+/**
+ * Simulating a CLMM swap locally, bin by bin.
+ *
+ * Mirrors the range's own swap arithmetic step for step. This is what makes a
+ * quote possible without asking any backend: given the range's bins and
+ * current price — both readable from raw account state — the result is the
+ * same arithmetic the range will perform on chain.
+ */
+/** Fee shares are stored as basis points and converted to Q128 fractions. */
+function feeFraction(bps) {
+    return mulDivFloor(BigInt(bps), SCALE, 10000n);
+}
+/** How much gross X this bin can absorb before the price reaches its lower bound. */
+function maxXInThisBin(args) {
+    if (args.sqrtP <= args.sqrtPa)
+        return 0n;
+    const invChange = q128DivCeil(SCALE, args.sqrtPa) - q128DivFloor(SCALE, args.sqrtP);
+    const needed = q128MulCeil(invChange > 0n ? invChange : 0n, args.liquidity);
+    const gross = q128DivCeil(needed, SCALE - args.lpFee);
+    return args.remaining < gross ? args.remaining : gross;
+}
+/** How much gross Y this bin can absorb before the price reaches its upper bound. */
+function maxYInThisBin(args) {
+    if (args.sqrtP >= args.sqrtPb)
+        return 0n;
+    const needed = q128MulCeil(args.sqrtPb - args.sqrtP, args.liquidity);
+    const gross = q128DivCeil(needed, SCALE - args.lpFee);
+    return args.remaining < gross ? args.remaining : gross;
+}
+function stepXToY(args) {
+    const { sqrtPa } = binBounds(args.bin, args.binStep);
+    const gross = maxXInThisBin({
+        remaining: args.remaining,
+        sqrtPa,
+        liquidity: args.liquidity,
+        sqrtP: args.sqrtP,
+        lpFee: args.lpFee,
+    });
+    if (gross === 0n) {
+        return {
+            bin: args.bin,
+            newSqrtPrice: args.sqrtP,
+            out: 0n,
+            remaining: args.remaining,
+            lpFee: 0n,
+            protocolFee: 0n,
+        };
+    }
+    const fee = q128Mul(args.lpFee, gross);
+    const afterFee = gross - fee;
+    const invChange = q128DivFloor(afterFee, args.liquidity);
+    const newInv = q128DivFloor(SCALE, args.sqrtP) + invChange;
+    const unclamped = q128DivCeil(SCALE, newInv);
+    const capped = unclamped < args.sqrtP ? unclamped : args.sqrtP;
+    const newSqrtPrice = capped > sqrtPa ? capped : sqrtPa;
+    const outGross = q128MulFloor(args.liquidity, args.sqrtP - newSqrtPrice);
+    const protocolFee = q128Mul(outGross, args.protocolFee);
+    return {
+        bin: args.bin,
+        newSqrtPrice,
+        out: outGross - protocolFee,
+        remaining: args.remaining - gross,
+        lpFee: fee,
+        protocolFee,
+    };
+}
+function stepYToX(args) {
+    const { sqrtPa, sqrtPb } = binBounds(args.bin, args.binStep);
+    const gross = maxYInThisBin({
+        remaining: args.remaining,
+        sqrtPb,
+        liquidity: args.liquidity,
+        sqrtP: args.sqrtP,
+        lpFee: args.lpFee,
+    });
+    if (gross === 0n) {
+        return {
+            bin: args.bin,
+            newSqrtPrice: args.sqrtP,
+            out: 0n,
+            remaining: args.remaining,
+            lpFee: 0n,
+            protocolFee: 0n,
+        };
+    }
+    const fee = q128Mul(args.lpFee, gross);
+    const afterFee = gross - fee;
+    const change = q128DivFloor(afterFee, args.liquidity);
+    const unclamped = args.sqrtP + change;
+    const capped = unclamped < sqrtPb ? unclamped : sqrtPb;
+    const newSqrtPrice = capped > sqrtPa ? capped : sqrtPa;
+    const invOld = q128DivFloor(SCALE, args.sqrtP);
+    const invNew = q128DivCeil(SCALE, newSqrtPrice);
+    const invDelta = invOld > invNew ? invOld - invNew : 0n;
+    const outGross = q128MulFloor(invDelta, args.liquidity);
+    const protocolFee = q128Mul(outGross, args.protocolFee);
+    return {
+        bin: args.bin,
+        newSqrtPrice,
+        out: outGross - protocolFee,
+        remaining: args.remaining - gross,
+        lpFee: fee,
+        protocolFee,
+    };
+}
+/**
+ * Runs a swap against a range's bins.
+ *
+ * `xIn` decides direction: X in walks the price down through lower bins, Y in
+ * walks it up. The range stops after forty bins, so a swap large enough to
+ * cross more is refused here too, before it is signed.
+ */
+export function simulateClmmSwap(args) {
+    if (args.amountIn <= 0n)
+        throw new RangeError('amountIn must be positive');
+    const lpFee = feeFraction(args.lpFeeBps);
+    const protocolFee = feeFraction(args.protocolFeeBps);
+    const keys = [...args.bins.keys()].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    const liquidityOf = (bin) => args.bins.get(bin)?.l ?? 0n;
+    /** Next bin in the direction of travel, as the range picks it. */
+    const nextBin = (from) => {
+        if (args.xIn) {
+            let found = null;
+            for (const key of keys)
+                if (key < from)
+                    found = key;
+            return found;
+        }
+        for (const key of keys)
+            if (key > from)
+                return key;
+        return null;
+    };
+    let bin = BigInt(args.currentBin);
+    let sqrtP = args.currentSqrtPrice;
+    // As on chain: a missing current bin is
+    // skipped to the nearest one in the direction of travel.
+    if (!args.bins.has(bin)) {
+        const moved = nextBin(bin);
+        if (moved === null) {
+            return {
+                amountOut: 0n,
+                newSqrtPrice: sqrtP,
+                binsCrossed: [],
+                lpFees: 0n,
+                protocolFees: 0n,
+                unfilled: args.amountIn,
+            };
+        }
+        bin = moved;
+        sqrtP = args.xIn
+            ? sqrtPriceEnteringBin(Number(bin), args.binStep)
+            : sqrtPriceAtBin(Number(bin), args.binStep);
+    }
+    let remaining = args.amountIn;
+    let amountOut = 0n;
+    let lpFees = 0n;
+    let protocolFees = 0n;
+    const binsCrossed = [];
+    for (let iteration = 0;; iteration++) {
+        if (iteration >= MAX_BINS_PER_SWAP) {
+            throw new LimitExceededError('this swap would cross more bins than one transaction can', MAX_BINS_PER_SWAP, iteration + 1, 'Split it into smaller swaps.');
+        }
+        const liquidity = liquidityOf(bin);
+        const step = (args.xIn ? stepXToY : stepYToX)({
+            remaining,
+            bin: Number(bin),
+            liquidity,
+            sqrtP,
+            lpFee,
+            protocolFee,
+            binStep: args.binStep,
+        });
+        sqrtP = step.newSqrtPrice;
+        remaining = step.remaining;
+        amountOut += step.out;
+        lpFees += step.lpFee;
+        protocolFees += step.protocolFee;
+        if (!binsCrossed.includes(Number(bin)))
+            binsCrossed.push(Number(bin));
+        if (remaining <= 0n)
+            break;
+        const moved = nextBin(bin);
+        if (moved === null) {
+            // The range throws 5 here; report the rest as unfilled instead.
+            return {
+                amountOut,
+                newSqrtPrice: sqrtP,
+                binsCrossed,
+                lpFees,
+                protocolFees,
+                unfilled: remaining,
+            };
+        }
+        bin = moved;
+        sqrtP = args.xIn
+            ? sqrtPriceEnteringBin(Number(bin), args.binStep)
+            : sqrtPriceAtBin(Number(bin), args.binStep);
+    }
+    return { amountOut, newSqrtPrice: sqrtP, binsCrossed, lpFees, protocolFees, unfilled: 0n };
+}
+/**
+ * Turns a slippage tolerance into the Q128 price bound the range expects.
+ *
+ * CLMM bounds a swap by price, not by output: X in must keep the price above
+ * the bound, Y in must keep it below. Zero means unbounded, which on a live
+ * pool means accepting any price at all.
+ */
+export function sqrtPriceLimitFor(args) {
+    if (args.slippageBps <= 0)
+        return 0n;
+    // Tolerance is on price, the limit is on sqrt price: take the root of the factor.
+    const bound = args.xIn ? 10_000 - args.slippageBps : 10_000 + args.slippageBps;
+    const factor = mulDivFloor(BigInt(bound), SCALE, 10000n);
+    return q128Mul(args.currentSqrtPrice, q128Sqrt(factor));
+}
+/**
+ * Allowance for the range's integer rounding, which the real-number bound
+ * in {@link guaranteedOutAtLimit} ignores. Per crossed bin (at most forty)
+ * the range can lose up to:
+ *
+ *   input  — LP fee `q128Mul`, to nearest: ½ unit
+ *   input  — `q128DivCeil` of the bin's gross need:
+ *            ~2 units, on every bin the swap exhausts (all but the last)
+ *   output — `q128MulFloor`: 1 unit
+ *   output — protocol fee `q128Mul`, to nearest: ½ unit
+ */
+const DUST_IN = 4n * BigInt(MAX_BINS_PER_SWAP);
+const DUST_OUT = 2n * BigInt(MAX_BINS_PER_SWAP);
+/**
+ * Output guaranteed by the price limit, the only on-chain guard a CLMM swap has.
+ *
+ * A CLMM swap message carries no `minOut`: the range checks the price after
+ * every bin and refunds the whole input if the limit is crossed. The minimum
+ * received is therefore what follows from the limit, and this computes it.
+ *
+ * Price moves monotonically during a swap, so every chunk of input converts
+ * at a price no worse than the limit. The LP fee comes off the input and the
+ * protocol fee off the output:
+ *
+ *     xIn:  out ≥ (Δin − LP) · p_lim · (1 − f_pr)
+ *     yIn:  out ≥ (Δin − LP) / p_lim · (1 − f_pr),     p = (sqrtP/2¹²⁸)²
+ *
+ * The bound is deliberately loose. The quote places the limit one slippage
+ * tolerance beyond the post-trade price, so actual output usually exceeds
+ * the guarantee by about that tolerance; equality needs the whole swap to
+ * fill at the limit price.
+ *
+ * Rounding always goes against the caller: both fees round up and both
+ * price conversions round down.
+ */
+export function guaranteedOutAtLimit(args) {
+    // Zero disables the guard on chain, so nothing is guaranteed.
+    if (args.sqrtPriceLimit === 0n)
+        return 0n;
+    if (args.amountIn <= 0n)
+        return 0n;
+    const limit = args.sqrtPriceLimit;
+    // The range's fee fraction is mulDivFloor(bps, SCALE, 10000), never above
+    // bps/10000, so a ceiling is safe.
+    const netIn = args.amountIn - mulDivCeil(args.amountIn, BigInt(args.lpFeeBps), 10000n) - DUST_IN;
+    if (netIn <= 0n)
+        return 0n;
+    // Two floored Q128 steps instead of squaring the limit: same answer without
+    // a 512-bit intermediate, and each step rounds in the safe direction.
+    const grossOut = args.xIn
+        ? q128MulFloor(q128MulFloor(netIn, limit), limit)
+        : q128DivFloor(q128DivFloor(netIn, limit), limit);
+    if (grossOut <= 0n)
+        return 0n;
+    const netOut = grossOut - mulDivCeil(grossOut, BigInt(args.protocolFeeBps), 10000n) - DUST_OUT;
+    return netOut > 0n ? netOut : 0n;
+}
+//# sourceMappingURL=clmm-swap.js.map

package/dist/math/clmm-swap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clmm-swap.js","sourceRoot":"","sources":["../../src/math/clmm-swap.ts"],"names":[],"mappings":"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"}

package/dist/math/clmm.d.ts

@@ -0,0 +1,234 @@
+/**
+ * CLMM bin and price arithmetic, as the ranges compute it on chain.
+ *
+ * Liquidity is held in discrete bins whose price bounds form a geometric
+ * series with ratio `1 + binStep/10000`.
+ *
+ * Every upper bound is exactly the next bin's lower bound, including odd and
+ * negative bins; multiplying the lower bound by sqrt(1+beta) again would
+ * round differently from the range.
+ */
+/** Bins per range. A pool is split across several ranges. */
+export declare const BINS_PER_RANGE: number;
+/** Offset that centres range 0 on bin 0. */
+export declare const RANGE_OFFSET: number;
+/** Bin steps the factory accepts, in basis points. */
+export declare const BIN_STEPS: readonly [25, 50, 100, 200];
+/**
+ * A bin step the factory will accept.
+ *
+ * A union rather than an enum, because the package compiles under
+ * `erasableSyntaxOnly`; it still rejects `binStep: 30` at compile time.
+ */
+export type BinStep = (typeof BIN_STEPS)[number];
+/**
+ * The four bin steps. The digits are the value: `Bps25` is `25`.
+ *
+ * A narrower step concentrates liquidity harder — better fills, but the market
+ * leaves the position sooner.
+ */
+export declare const BinStep: {
+    /** 0.25% per bin — "micro bins", stable pairs. */
+    readonly Bps25: 25;
+    /** 0.50% per bin — "tight bins", stable pairs. */
+    readonly Bps50: 50;
+    /** 1.00% per bin — "wide bins", volatile pairs. */
+    readonly Bps100: 100;
+    /** 2.00% per bin — "broad bins", exotic pairs. */
+    readonly Bps200: 200;
+};
+/** Whether a number is one of the four the factory accepts. */
+export declare function isBinStep(value: number): value is BinStep;
+/** Range indices the protocol currently deploys. */
+export declare const RANGE_MIN: number;
+export declare const RANGE_MAX: number;
+/**
+ * Bins a single position may span.
+ *
+ * The deposit also aborts once it has burned 940 000 gas, so a wide deposit
+ * into an already-crowded range can fail below this cap; there is no way to
+ * know that before sending.
+ */
+export declare const MAX_BINS_PER_POSITION = 50;
+/** Bins one swap may cross before the range gives up. */
+export declare const MAX_BINS_PER_SWAP = 40;
+/** First bin belonging to a range. */
+export declare function firstBinOfRange(range: number): number;
+/** Last bin belonging to a range. */
+export declare function lastBinOfRange(range: number): number;
+/**
+ * Which range holds a bin.
+ *
+ * Rounds down, not toward zero. TVM divides toward negative infinity, and the
+ * difference is not academic: bin −1025 belongs to range −1, but truncation
+ * would put it in range 0 and send the message to a range that does not
+ * own that bin.
+ */
+export declare function rangeOfBin(bin: number): number;
+/** Lowest and highest bins any deployed range covers. */
+export declare function binCoverage(): {
+    min: number;
+    max: number;
+};
+/** `1 + binStep/10000` in Q128, as the range computes it. */
+export declare function onePlusBeta(binStep: number): bigint;
+/** Square root of {@link onePlusBeta}, in Q128. */
+export declare function sqrtOnePlusBeta(binStep: number): bigint;
+/**
+ * Lower price bound of a bin, as a Q128 square root.
+ *
+ * Odd bins are computed as `(1+β)^(n>>1) · sqrt(1+β)` rather than by raising to
+ * a half power — matching the range's own shortcut, rounding included.
+ */
+export declare function sqrtPriceAtBin(bin: number, binStep: number): bigint;
+/**
+ * Upper bound of a bin, where a swap moving the price down enters it. The
+ * range uses this same boundary for liquidity and swap arithmetic.
+ */
+export declare function sqrtPriceEnteringBin(bin: number, binStep: number): bigint;
+/** Both price bounds of a bin, as Q128 square roots. */
+export declare function binBounds(bin: number, binStep: number): {
+    sqrtPa: bigint;
+    sqrtPb: bigint;
+};
+/**
+ * Price from a Q128 square root, as a JavaScript number.
+ *
+ * For display only. The value is squared and scaled down, so it loses
+ * precision — never feed it back into anything that builds a transaction.
+ */
+export declare function sqrtPriceToPrice(sqrtPrice: bigint, decimalsX?: number, decimalsY?: number): number;
+/**
+ * The bin containing a price expressed in **raw** units — token Y per token X
+ * before decimals are applied.
+ *
+ * Containment, not proximity. A bin owns the half-open interval
+ * `[Pa(n), Pa(n+1))`, so a price anywhere in the upper part of a bin still
+ * belongs to that bin and not to the next one. When you want the closest
+ * boundary instead, ask for it by name: {@link nearestBinToRawPrice}.
+ *
+ * Named apart from `pool.binAtPrice`, which takes the price as a person would
+ * write it. Feeding a human price here puts the bin thousands of steps away
+ * whenever the two assets have different decimals.
+ */
+export declare function binAtRawPrice(rawPrice: number, binStep: number): number;
+/**
+ * The bin whose lower bound lies **closest** to a raw price — the nearest
+ * boundary, not the bin the price falls into.
+ *
+ * Only pool creation wants this: the factory accepts any `initBin`, and
+ * rounding to the nearest boundary opens the pool at the price the creator
+ * actually asked for rather than up to a whole bin below it. Everything that
+ * asks "where does this price live?" wants {@link binAtRawPrice}.
+ */
+export declare function nearestBinToRawPrice(rawPrice: number, binStep: number): number;
+/** Human-readable price of a bin, decimals applied. */
+export declare function priceAtBin(bin: number, binStep: number, decimalsX?: number, decimalsY?: number): number;
+/**
+ * Converts a human price into a bin, accounting for the two tokens' decimals.
+ *
+ * A pool of TON (9 decimals) against a 6-decimal jetton prices very differently
+ * in raw units than it does on screen; getting this wrong puts a position
+ * thousands of bins away from the market.
+ */
+export declare function binAtHumanPrice(args: {
+    price: number;
+    binStep: number;
+    decimalsX: number;
+    decimalsY: number;
+}): number;
+/**
+ * {@link nearestBinToRawPrice} for a human price, decimals accounted for.
+ *
+ * The counterpart of {@link binAtHumanPrice}: nearest boundary rather than
+ * containment. Pool creation is the one caller that means it.
+ */
+export declare function nearestBinToHumanPrice(args: {
+    price: number;
+    binStep: number;
+    decimalsX: number;
+    decimalsY: number;
+}): number;
+export type Contribution = {
+    /** Liquidity credited to the position for this bin. */
+    liquidity: bigint;
+    /** Amounts actually consumed. */
+    used: {
+        x: bigint;
+        y: bigint;
+    };
+    /** Amounts handed back because the bin could not absorb them. */
+    refund: {
+        x: bigint;
+        y: bigint;
+    };
+};
+/**
+ * What one bin does with the amounts offered to it.
+ *
+ * A bin below the current price takes only Y; one above takes only X; the bin
+ * holding the current price takes both, in the ratio its bounds dictate. The
+ * side that runs out first caps the liquidity, and the excess is refunded —
+ * which is why an unbalanced deposit silently returns part of itself.
+ */
+export declare function contributeLiquidity(args: {
+    bin: number;
+    currentSqrtPrice: bigint;
+    x: bigint;
+    y: bigint;
+    binStep: number;
+}): Contribution;
+/**
+ * What one bin of a position is worth right now.
+ *
+ * Mirrors a withdrawal from the range: liquidity is converted
+ * back into both sides at the price clamped to the bin's own bounds, so a bin
+ * the price has moved past holds only one of them.
+ */
+export declare function binValue(args: {
+    bin: number;
+    liquidity: bigint;
+    currentSqrtPrice: bigint;
+    binStep: number;
+}): {
+    x: bigint;
+    y: bigint;
+};
+/**
+ * Fees one bin owes a position.
+ *
+ * Mirrors the on-chain fee payout: the range keeps a per-unit-of-liquidity
+ * accumulator per bin, the position keeps the value it last settled at, and
+ * what is owed is the growth times the position's liquidity in that bin.
+ */
+export declare function binFees(args: {
+    liquidity: bigint;
+    /** The range's current accumulators for this bin. */
+    binFees: {
+        x: bigint;
+        y: bigint;
+    };
+    /** The position's checkpoint of those accumulators. */
+    checkpoint: {
+        x: bigint;
+        y: bigint;
+    };
+}): {
+    x: bigint;
+    y: bigint;
+};
+/**
+ * Which side or sides a bin can take, given where the price sits.
+ *
+ * Useful before building a deposit: offering X to a bin that only takes Y
+ * gets it refunded, minus the gas spent finding out.
+ */
+export declare function binSides(args: {
+    bin: number;
+    currentSqrtPrice: bigint;
+    binStep: number;
+}): {
+    takesX: boolean;
+    takesY: boolean;
+};
+//# sourceMappingURL=clmm.d.ts.map

package/dist/math/clmm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clmm.d.ts","sourceRoot":"","sources":["../../src/math/clmm.ts"],"names":[],"mappings":"AAcA;;;;;;;;;GASG;AAEH,6DAA6D;AAC7D,eAAO,MAAM,cAAc,QAA+C,CAAA;AAC1E,4CAA4C;AAC5C,eAAO,MAAM,YAAY,QAA6C,CAAA;AACtE,sDAAsD;AACtD,eAAO,MAAM,SAAS,6BAA8B,CAAA;AAEpD;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAA;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,OAAO;IAClB,kDAAkD;;IAElD,kDAAkD;;IAElD,mDAAmD;;IAEnD,kDAAkD;;CAER,CAAA;AAE5C,+DAA+D;AAC/D,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,OAAO,CAEzD;AACD,oDAAoD;AACpD,eAAO,MAAM,SAAS,QAA0C,CAAA;AAChE,eAAO,MAAM,SAAS,QAA0C,CAAA;AAChE;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,KAAK,CAAA;AACvC,yDAAyD;AACzD,eAAO,MAAM,iBAAiB,KAAK,CAAA;AAEnC,sCAAsC;AACtC,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,qCAAqC;AACrC,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,yDAAyD;AACzD,wBAAgB,WAAW,IAAI;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAE1D;AAED,6DAA6D;AAC7D,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,mDAAmD;AACnD,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAInE;AAQD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEzE;AAED,wDAAwD;AACxD,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAK1F;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,SAAI,EAAE,SAAS,SAAI,GAAG,MAAM,CAGxF;AAeD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAMvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED,uDAAuD;AACvD,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,SAAI,EAAE,SAAS,SAAI,GAAG,MAAM,CAE7F;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;CAClB,GAAG,MAAM,CAGT;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;CAClB,GAAG,MAAM,CAGT;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAA;IACjB,iCAAiC;IACjC,IAAI,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC9B,iEAAiE;IACjE,MAAM,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CACjC,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,GAAG,EAAE,MAAM,CAAA;IACX,gBAAgB,EAAE,MAAM,CAAA;IACxB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,OAAO,EAAE,MAAM,CAAA;CAChB,GAAG,YAAY,CA0Bf;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,MAAM,CAAA;IACjB,gBAAgB,EAAE,MAAM,CAAA;IACxB,OAAO,EAAE,MAAM,CAAA;CAChB,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAW3B;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE;IAC5B,SAAS,EAAE,MAAM,CAAA;IACjB,qDAAqD;IACrD,OAAO,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACjC,uDAAuD;IACvD,UAAU,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CACrC,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAO3B;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,gBAAgB,EAAE,MAAM,CAAA;IACxB,OAAO,EAAE,MAAM,CAAA;CAChB,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAMvC"}