@moon-cx/sdk 0.0.0-stage → 2.0.1

package/dist/ops/mempad.js

@@ -0,0 +1,248 @@
+import { BuildError, LimitExceededError } from "../core/errors.js";
+import { FEE_BPS } from "../core/fee.js";
+import { mempadBuyGas } from "../core/gas.js";
+import { randomQueryId } from "../core/tx.js";
+import * as mempad from "../codec/mempad.js";
+import { mempadCurveAddress } from "../state/address.js";
+/*
+ * Mempad: launching a token on a bonding curve and trading against it. Built
+ * offline; only the factory's `launchFee` (in its c4, changes on upgrade) has to
+ * be read from chain. `Moon.createCurve` reads it for you.
+ *
+ * - create: the factory keeps its launch fee and forwards the rest to the curve.
+ * - buy: the curve subtracts its gas overhead from the attached value, so `value`
+ *   here is the purchase and the computed gas ({@link mempadBuyGas}) rides on top.
+ * - sell: a sale is a burn with a marker. Without it a trading curve refuses (555)
+ *   and a graduated one burns the tokens and pays nothing.
+ */
+/**
+ * Pool fee tiers the factory accepts; anything else is `INVALID_PAYLOAD` (700).
+ * Same as CPMM's {@link FEE_BPS}: it is the fee of the CPMM pool the curve graduates into.
+ */
+export const MEMPAD_FEE_BPS = FEE_BPS;
+/**
+ * Trade and creator fees per tier, from the factory's `feesForTier`.
+ * The creator's cut is not a fixed share of the trade fee.
+ */
+export const MEMPAD_FEE_TIERS = {
+    10: { tradeFeeBps: 20, creatorFeeBps: 10 },
+    20: { tradeFeeBps: 40, creatorFeeBps: 30 },
+    30: { tradeFeeBps: 60, creatorFeeBps: 50 },
+    50: { tradeFeeBps: 100, creatorFeeBps: 80 },
+    100: { tradeFeeBps: 200, creatorFeeBps: 150 },
+    200: { tradeFeeBps: 400, creatorFeeBps: 300 },
+};
+/**
+ * Default sell attachment in nanograms: 0.06 GRAM, not the wallet's 0.05 gate
+ * (exit 48). The burn notification
+ * forwards what is left in mode 64, and at exactly 0.05 the curve falls short of its
+ * own gate. The unspent part is returned with the payout.
+ */
+export const MEMPAD_SELL_ATTACH = 60000000n;
+/** The wallet's own floor. Attaching less is exit 48 before anything happens. */
+export const MEMPAD_SELL_MIN_ATTACH = mempad.MEMPAD_VALUE_JETTON_TRANSFER;
+/**
+ * Value a deploy must attach: the factory's flat cost, the launch fee and the initial buy.
+ * Gas for the initial buy is not added: the curve covers it from the flat cost.
+ */
+export function createLaunchValue(launchFee, initialBuy) {
+    return mempad.MEMPAD_VALUE_CREATE_LAUNCH + launchFee + initialBuy;
+}
+/**
+ * Message value for a purchase of `net` nanograms: `net` plus the computed gas
+ * ({@link mempadBuyGas}), as {@link buildCurveBuy} attaches by default.
+ * `prices` is only for a chain whose config 21 differs from mainnet's.
+ */
+export function buyValueForSpend(net, prices) {
+    const gas = mempadBuyGas(prices).overhead;
+    if (net < mempad.MEMPAD_VALUE_MIN_BUY) {
+        throw new BuildError(`mempad buy: the curve's minimum is ${mempad.MEMPAD_VALUE_MIN_BUY} nanograms ` +
+            `(VALUE_MIN_BUY), got ${net}`);
+    }
+    return net + gas;
+}
+// Bytes the factory rejects in name and symbol: below 0x20, and 0x7f. Kept as
+// escapes: a literal control byte in source is invisible and easily lost.
+const CONTROL_BYTE = /[\u0000-\u001f\u007f]/;
+function byteLength(text) {
+    return Buffer.from(text, 'utf8').length;
+}
+function checkField(value, field, maxBytes, maxCells) {
+    const bytes = byteLength(value);
+    if (bytes === 0) {
+        throw new BuildError(`mempad create: ${field} is empty — snakeField asserts bits > 0 ` +
+            '(INVALID_METADATA 701)');
+    }
+    if (bytes > maxBytes) {
+        throw new LimitExceededError(`mempad create: ${field} in bytes`, maxBytes, bytes, 'The factory counts BYTES, not characters — Cyrillic costs two per letter and an emoji ' +
+            'four (INVALID_METADATA 701).');
+    }
+    const cells = mempad.snakeCells(value);
+    if (maxCells !== null && cells > maxCells) {
+        throw new LimitExceededError(`mempad create: ${field} in cells`, maxCells, cells, 'snakeField asserts the chain is strictly linear, so it cannot be split differently.');
+    }
+}
+/**
+ * Builds a token launch: one message to the factory.
+ *
+ * `launchFee` has no default: it lives in the factory's c4 and can change on upgrade.
+ * Pass `curveCode` (also from c4) to predict the curve address. A repeated
+ * `(factory, creator, salt)` does not throw but the factory keeps the fee, so check
+ * the predicted address for an existing curve before signing.
+ */
+export function buildCreateCurve(args) {
+    if (!MEMPAD_FEE_BPS.includes(args.feeBps)) {
+        throw new BuildError(`mempad create: fee must be one of ${MEMPAD_FEE_BPS.join(', ')} basis points, ` +
+            `got ${args.feeBps} (INVALID_PAYLOAD 700)`);
+    }
+    const initialBuy = args.initialBuy ?? 0n;
+    if (initialBuy < 0n)
+        throw new BuildError('mempad create: initialBuy is negative');
+    if (initialBuy !== 0n && initialBuy < mempad.MEMPAD_VALUE_MIN_BUY) {
+        throw new BuildError(`mempad create: initialBuy must be exactly 0 or at least ${mempad.MEMPAD_VALUE_MIN_BUY} ` +
+            `nanograms, got ${initialBuy} (INVALID_PAYLOAD 700). ` +
+            'The factory checks this after it has taken the launch fee.');
+    }
+    if (args.launchFee < 0n)
+        throw new BuildError('mempad create: launchFee is negative');
+    const meta = args.metadata;
+    const limits = mempad.MEMPAD_META_LIMITS;
+    checkField(meta.name, 'name', limits.nameBytes, 1);
+    checkField(meta.symbol, 'symbol', limits.symbolBytes, 1);
+    checkField(meta.image, 'image', limits.imageBytes, limits.imageCells);
+    if (meta.description) {
+        checkField(meta.description, 'description', limits.descriptionBytes, limits.descriptionCells);
+    }
+    for (const [field, value] of Object.entries(meta.links ?? {})) {
+        if (value)
+            checkField(value, `links.${field}`, limits.linkBytes, 1);
+    }
+    // Only name and symbol are scanned, matching the factory.
+    for (const [field, value] of [['name', meta.name], ['symbol', meta.symbol]]) {
+        if (CONTROL_BYTE.test(value)) {
+            throw new BuildError(`mempad create: ${field} contains a control byte — every byte must be >= 0x20 and != 0x7f ` +
+                '(INVALID_METADATA 701)');
+        }
+    }
+    if (meta.links && !meta.description) {
+        throw new BuildError('mempad create: links need a description — the on-chain metadata layout declares it ' +
+            '`cell`, not `cell?`, so links without one cannot be encoded');
+    }
+    const salt = args.salt ?? randomQueryId();
+    const queryId = args.queryId ?? salt & 0xffffffffn;
+    const tier = MEMPAD_FEE_TIERS[args.feeBps];
+    return {
+        txs: [
+            {
+                to: args.factory,
+                value: createLaunchValue(args.launchFee, initialBuy),
+                body: mempad.encodeCreateLaunch({
+                    queryId,
+                    salt,
+                    feeBps: args.feeBps,
+                    initialBuy,
+                    content: mempad.encodeLaunchContent(meta),
+                }),
+            },
+        ],
+        queryId,
+        details: {
+            salt,
+            feeBps: args.feeBps,
+            tradeFeeBps: tier.tradeFeeBps,
+            creatorFeeBps: tier.creatorFeeBps,
+            initialBuy,
+            launchFee: args.launchFee,
+            curve: args.curveCode
+                ? mempadCurveAddress({
+                    factory: args.factory,
+                    creator: args.creator,
+                    salt,
+                    curveCode: args.curveCode,
+                })
+                : null,
+        },
+        warnings: [],
+    };
+}
+/**
+ * Builds a purchase on the curve.
+ *
+ * `value` is the purchase, not the TON message value: the curve computes
+ * `gross = msgValue - requiredGas`, so by default the computed overhead
+ * ({@link mempadBuyGas}) is added on top and exactly `value` reaches the curve.
+ * Pass `gasIncluded: true` to make `value` the whole message instead (for example,
+ * to spend a wallet's last GRAM).
+ */
+export function buildCurveBuy(args) {
+    const gas = mempadBuyGas(args.prices);
+    const minOut = args.minOut ?? 0n;
+    if (minOut < 0n)
+        throw new BuildError('mempad buy: minOut is negative');
+    if (args.value < 0n)
+        throw new BuildError('mempad buy: value is negative');
+    const value = args.gasIncluded === true ? args.value : args.value + gas.overhead;
+    const spend = value - gas.overhead;
+    if (spend < mempad.MEMPAD_VALUE_MIN_BUY) {
+        throw new BuildError(args.gasIncluded === true
+            ? `mempad buy: value ${args.value} is below the curve's gate of ${gas.minimum} ` +
+                `nanograms — the curve takes ${gas.overhead} for gas first, leaving ${spend} to buy ` +
+                `with, and the curve answers LOW_AMOUNT (510). ${gas.gate}`
+            : `mempad buy: the curve's smallest purchase is ${mempad.MEMPAD_VALUE_MIN_BUY} nanograms ` +
+                `(VALUE_MIN_BUY), got ${args.value} — the curve answers LOW_AMOUNT (510). ` +
+                'Gas is not the problem here: it is already ' +
+                'being added on top of this number.');
+    }
+    const queryId = args.queryId ?? randomQueryId();
+    return {
+        txs: [{ to: args.curve, value, body: mempad.encodeBuy({ queryId, minOut }) }],
+        queryId,
+        details: { value, requiredGas: gas.overhead, spend, minOut },
+        warnings: [],
+    };
+}
+/**
+ * Builds a sale back to the curve.
+ *
+ * The message goes to the seller's own jetton wallet, not to the curve. That
+ * address is sharded (not the plain state-init hash), so derive it with
+ * `mempadJettonWalletAddress`. `owner` becomes `sendExcessesTo`, where the change goes.
+ */
+export function buildCurveSell(args) {
+    if (args.amount <= 0n) {
+        throw new BuildError('mempad sell: amount must be greater than zero');
+    }
+    const minOut = args.minOut ?? 0n;
+    if (minOut < 0n)
+        throw new BuildError('mempad sell: minOut is negative');
+    const attach = args.attach ?? MEMPAD_SELL_ATTACH;
+    if (attach < MEMPAD_SELL_MIN_ATTACH) {
+        throw new BuildError(`mempad sell: attaching ${attach} is below the wallet's gate of ${MEMPAD_SELL_MIN_ATTACH} ` +
+            'nanograms — it answers NotEnoughGas (48)');
+    }
+    const queryId = args.queryId ?? randomQueryId();
+    const warnings = [];
+    if (attach < MEMPAD_SELL_ATTACH) {
+        warnings.push(`attaching ${attach} clears the wallet's gate but may leave the curve short: ` +
+            'the burn notification carries what is left of this value, and the surplus ' +
+            'is returned with the payout anyway');
+    }
+    return {
+        txs: [
+            {
+                to: args.jettonWallet,
+                value: attach,
+                body: mempad.encodeAskToBurn({
+                    queryId,
+                    jettonAmount: args.amount,
+                    sendExcessesTo: args.owner,
+                    customPayload: mempad.encodeSellPayload({ minOut }),
+                }),
+            },
+        ],
+        queryId,
+        details: { amount: args.amount, minOut, attach },
+        warnings,
+    };
+}
+//# sourceMappingURL=mempad.js.map

package/dist/ops/mempad.js.map

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

package/dist/ops/pool.d.ts

@@ -0,0 +1,75 @@
+import type { Address } from '@ton/core';
+import { type Asset } from '../core/asset.ts';
+import { type FeeBps } from '../core/fee.ts';
+import { type BuiltOperation } from '../core/tx.ts';
+import { type BinStep } from '../math/clmm.ts';
+/** Minimum the CPMM factory accepts to deploy a pool, in nanotons. */
+export declare const CPMM_CREATE_POOL_GAS = 1000000000n;
+/** Value attached to a CPMM pool deployment: the gate plus margin for the deploy cascade. */
+export declare const CPMM_CREATE_POOL_ATTACH = 1200000000n;
+/** Minimum the CLMM factory accepts, in nanotons. It deploys three ranges. */
+export declare const CLMM_CREATE_POOL_GAS = 4000000000n;
+/** Value attached to a CLMM pool deployment, with margin. */
+export declare const CLMM_CREATE_POOL_ATTACH = 4200000000n;
+export type PoolCreation = {
+    /** The pair as the factory will store it. */
+    x: Asset;
+    y: Asset;
+    /** True when the factory's order is the reverse of what you passed. */
+    inverted: boolean;
+};
+export type CpmmPoolCreation = PoolCreation & {
+    /** The fee chosen by the creator; stored in the pool forever. */
+    lpFeeBps: number;
+    /** The factory's own cut, derived from `lpFeeBps` — shown, never sent. */
+    protocolFeeBps: number;
+};
+export type ClmmPoolCreation = PoolCreation & {
+    binStep: BinStep;
+    /** The starting bin, computed for the pair in the factory's order. */
+    initBin: number;
+    /** The price that bin actually represents, in the factory's orientation. */
+    initPrice: number;
+    /** Which range will hold the starting price. */
+    rangeNum: number;
+};
+/** Pool fees the CPMM factory accepts, in basis points. Alias of {@link FEE_BPS}. */
+export declare const CPMM_FEE_BPS: readonly [10, 20, 30, 50, 100, 200];
+export type CpmmFeeBps = FeeBps;
+/**
+ * Builds a CPMM pool deployment. The factory orders the pair itself; CPMM carries
+ * no price, so the order does not matter to the caller.
+ */
+export declare function buildCpmmCreatePool(args: {
+    factory: Address;
+    assetA: Asset;
+    assetB: Asset;
+    /**
+     * Basis points: 10 = 0.10%, 20 = 0.20%, 30 = 0.30%, 50 = 0.50%,
+     * 100 = 1.00%, 200 = 2.00%. Write the number, or `FeeTier.Bps30`.
+     * Stored in the pool forever.
+     */
+    feeBps: CpmmFeeBps;
+    queryId?: bigint;
+}): BuiltOperation<CpmmPoolCreation>;
+/**
+ * Builds a CLMM pool deployment.
+ *
+ * `price` is how many `assetB` one `assetA` buys, written as a person would.
+ * If the factory's order turns out to be the other way round, the price is
+ * inverted along with the pair, so the pool opens where you meant it to.
+ */
+export declare function buildClmmCreatePool(args: {
+    factory: Address;
+    assetA: Asset;
+    assetB: Asset;
+    /**
+     * Basis points per bin: 25 = 0.25%, 50 = 0.50%, 100 = 1.00%, 200 = 2.00%.
+     * Write the number, or `BinStep.Bps25`.
+     */
+    binStep: BinStep;
+    /** Starting price: units of `assetB` per one `assetA`. */
+    price: number;
+    queryId?: bigint;
+}): BuiltOperation<ClmmPoolCreation>;
+//# sourceMappingURL=pool.d.ts.map

package/dist/ops/pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../src/ops/pool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACxC,OAAO,EAAe,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAE1D,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAA;AAGlE,OAAO,EAQL,KAAK,OAAO,EACb,MAAM,iBAAiB,CAAA;AAOxB,sEAAsE;AACtE,eAAO,MAAM,oBAAoB,cAAiB,CAAA;AAClD,6FAA6F;AAC7F,eAAO,MAAM,uBAAuB,cAAiB,CAAA;AAErD,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,cAAiB,CAAA;AAClD,6DAA6D;AAC7D,eAAO,MAAM,uBAAuB,cAAiB,CAAA;AAErD,MAAM,MAAM,YAAY,GAAG;IACzB,6CAA6C;IAC7C,CAAC,EAAE,KAAK,CAAA;IACR,CAAC,EAAE,KAAK,CAAA;IACR,uEAAuE;IACvE,QAAQ,EAAE,OAAO,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG;IAC5C,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAA;IAChB,0EAA0E;IAC1E,cAAc,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG;IAC5C,OAAO,EAAE,OAAO,CAAA;IAChB,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAA;IACf,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAA;IACjB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,qFAAqF;AACrF,eAAO,MAAM,YAAY,qCAAU,CAAA;AACnC,MAAM,MAAM,UAAU,GAAG,MAAM,CAAA;AAa/B;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,KAAK,CAAA;IACb,MAAM,EAAE,KAAK,CAAA;IACb;;;;OAIG;IACH,MAAM,EAAE,UAAU,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,GAAG,cAAc,CAAC,gBAAgB,CAAC,CAiCnC;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,KAAK,CAAA;IACb,MAAM,EAAE,KAAK,CAAA;IACb;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAA;IAChB,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,GAAG,cAAc,CAAC,gBAAgB,CAAC,CAqEnC"}

package/dist/ops/pool.js

@@ -0,0 +1,129 @@
+import { orderAssets } from "../core/asset.js";
+import { BuildError, LimitExceededError } from "../core/errors.js";
+import { FEE_BPS } from "../core/fee.js";
+import { randomQueryId } from "../core/tx.js";
+import * as cpmmCodec from "../codec/cpmm.js";
+import * as clmmCodec from "../codec/clmm.js";
+import { BIN_STEPS, RANGE_MAX, RANGE_MIN, isBinStep, nearestBinToHumanPrice, priceAtBin, rangeOfBin, } from "../math/clmm.js";
+/*
+ * The factories reorder the pair's masters but leave every other field alone, so a
+ * starting price must be inverted along with the pair or the pool opens at the inverse.
+ */
+/** Minimum the CPMM factory accepts to deploy a pool, in nanotons. */
+export const CPMM_CREATE_POOL_GAS = 1000000000n;
+/** Value attached to a CPMM pool deployment: the gate plus margin for the deploy cascade. */
+export const CPMM_CREATE_POOL_ATTACH = 1200000000n;
+/** Minimum the CLMM factory accepts, in nanotons. It deploys three ranges. */
+export const CLMM_CREATE_POOL_GAS = 4000000000n;
+/** Value attached to a CLMM pool deployment, with margin. */
+export const CLMM_CREATE_POOL_ATTACH = 4200000000n;
+/** Pool fees the CPMM factory accepts, in basis points. Alias of {@link FEE_BPS}. */
+export const CPMM_FEE_BPS = FEE_BPS;
+// Protocol fee per tier as the factory derives it (`protocolFeeFor`).
+// Never sent; surfaced in `details` so the full swap fee can be shown.
+const PROTOCOL_FEE_FOR = {
+    10: 5,
+    20: 10,
+    30: 10,
+    50: 20,
+    100: 20,
+    200: 50,
+};
+/**
+ * Builds a CPMM pool deployment. The factory orders the pair itself; CPMM carries
+ * no price, so the order does not matter to the caller.
+ */
+export function buildCpmmCreatePool(args) {
+    // Checked at runtime too: JavaScript callers can pass any number.
+    if (!CPMM_FEE_BPS.includes(args.feeBps)) {
+        throw new BuildError(`pool fee must be one of ${CPMM_FEE_BPS.join(', ')} basis points, got ${args.feeBps}`);
+    }
+    const { x, y, inverted } = orderAssets(args.assetA, args.assetB);
+    const queryId = args.queryId ?? randomQueryId();
+    return {
+        txs: [
+            {
+                to: args.factory,
+                value: CPMM_CREATE_POOL_ATTACH,
+                body: cpmmCodec.encodeCreatePool({
+                    queryId,
+                    xMaster: x.master,
+                    yMaster: y.master,
+                    feeBps: args.feeBps,
+                }),
+            },
+        ],
+        queryId,
+        details: {
+            x,
+            y,
+            inverted,
+            lpFeeBps: args.feeBps,
+            protocolFeeBps: PROTOCOL_FEE_FOR[args.feeBps],
+        },
+        warnings: [],
+    };
+}
+/**
+ * Builds a CLMM pool deployment.
+ *
+ * `price` is how many `assetB` one `assetA` buys, written as a person would.
+ * If the factory's order turns out to be the other way round, the price is
+ * inverted along with the pair, so the pool opens where you meant it to.
+ */
+export function buildClmmCreatePool(args) {
+    // Checked at runtime too: JavaScript callers and parsed state can pass any number.
+    if (!isBinStep(args.binStep)) {
+        throw new BuildError(`bin step must be one of ${BIN_STEPS.join(', ')} basis points, got ${args.binStep}`);
+    }
+    if (!(args.price > 0) || !Number.isFinite(args.price)) {
+        throw new BuildError('the starting price must be a finite number greater than zero');
+    }
+    const { x, y, inverted } = orderAssets(args.assetA, args.assetB);
+    const price = inverted ? 1 / args.price : args.price;
+    // Deliberately the nearest bin, not the one containing the price: the factory accepts
+    // any initBin inside the ranges, and nearest keeps the
+    // drift under binStep/2, while flooring would trip the drift warning below for about half of all pools.
+    const initBin = nearestBinToHumanPrice({
+        price,
+        binStep: args.binStep,
+        decimalsX: x.decimals,
+        decimalsY: y.decimals,
+    });
+    const rangeNum = rangeOfBin(initBin);
+    if (rangeNum < RANGE_MIN || rangeNum > RANGE_MAX) {
+        throw new LimitExceededError(`a starting price of ${args.price} lands on bin ${initBin}, outside the ranges the ` +
+            'factory deploys', RANGE_MAX, rangeNum, `Bins ${RANGE_MIN * 2048 - 1024}…${RANGE_MAX * 2048 + 1023} are available at this bin step.`);
+    }
+    const queryId = args.queryId ?? randomQueryId();
+    const initPrice = priceAtBin(initBin, args.binStep, x.decimals, y.decimals);
+    const warnings = [];
+    if (inverted) {
+        warnings.push(`the factory stores this pair as ${x.symbol ?? x.toString()}/${y.symbol ?? y.toString()}, ` +
+            `so the starting price was inverted to ${initPrice}`);
+    }
+    // Bins quantise the price; warn when the drift exceeds half a step.
+    const drift = Math.abs(initPrice - (inverted ? 1 / args.price : args.price));
+    if (drift / initPrice > args.binStep / 10_000 / 2) {
+        warnings.push(`the nearest bin prices this pool at ${initPrice}, not exactly what you asked`);
+    }
+    return {
+        txs: [
+            {
+                to: args.factory,
+                value: CLMM_CREATE_POOL_ATTACH,
+                body: clmmCodec.encodeCreatePool({
+                    queryId,
+                    xMaster: x.master,
+                    yMaster: y.master,
+                    binStep: args.binStep,
+                    initBin,
+                }),
+            },
+        ],
+        queryId,
+        details: { x, y, inverted, binStep: args.binStep, initBin, initPrice, rangeNum },
+        warnings,
+    };
+}
+//# sourceMappingURL=pool.js.map

package/dist/ops/pool.js.map

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

package/dist/ops/position.d.ts

@@ -0,0 +1,47 @@
+import type { Address } from '@ton/core';
+import { type BuiltOperation } from '../core/tx.ts';
+import type { ClmmPositionState, CpmmPoolState, CpmmPositionState } from '../state/storage.ts';
+/** Fees a CPMM position can collect right now. */
+export declare function cpmmPendingFees(args: {
+    position: CpmmPositionState;
+    pool: CpmmPoolState;
+}): {
+    x: bigint;
+    y: bigint;
+};
+/**
+ * Builds a fee collection. Works on a locked position too: locking stops
+ * withdrawals, not fee income.
+ */
+export declare function buildCollectFees(args: {
+    protocol: 'cpmm' | 'clmm';
+    position: Address;
+    /** CPMM only: a frozen position is mid-settlement and will reject. */
+    frozen?: boolean;
+    /** CLMM only: a position with a withdrawal or fee collection in flight will reject. */
+    pending?: boolean;
+    queryId?: bigint;
+}): BuiltOperation<{
+    protocol: 'cpmm' | 'clmm';
+}>;
+/** The exact phrase `lockForever` requires, so the call cannot be made by accident. */
+export declare const LOCK_CONFIRMATION = "lock this liquidity forever";
+export type LockArgs = {
+    protocol: 'cpmm' | 'clmm';
+    position: Address;
+    /**
+     * Must be exactly {@link LOCK_CONFIRMATION}. Neither protocol has an unlock
+     * message: a locked position keeps earning fees and never returns its principal.
+     */
+    confirm: string;
+    /** Already locked, read from the position's own state. */
+    alreadyLocked?: boolean;
+    queryId?: bigint;
+};
+/** Builds an irreversible position lock. The liquidity stays in the pool permanently; fees remain collectable. */
+export declare function buildLockForever(args: LockArgs): BuiltOperation<{
+    irreversible: true;
+}>;
+/** Whether a position is locked, from either protocol's state. */
+export declare function isLocked(state: CpmmPositionState | ClmmPositionState): boolean;
+//# sourceMappingURL=position.d.ts.map

package/dist/ops/position.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"position.d.ts","sourceRoot":"","sources":["../../src/ops/position.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAQxC,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAA;AAIlE,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE9F,kDAAkD;AAClD,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,QAAQ,EAAE,iBAAiB,CAAA;IAC3B,IAAI,EAAE,aAAa,CAAA;CACpB,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAM3B;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;IACzB,QAAQ,EAAE,OAAO,CAAA;IACjB,sEAAsE;IACtE,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,uFAAuF;IACvF,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,GAAG,cAAc,CAAC;IAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CAAC,CAqBhD;AAED,uFAAuF;AACvF,eAAO,MAAM,iBAAiB,gCAAgC,CAAA;AAE9D,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;IACzB,QAAQ,EAAE,OAAO,CAAA;IACjB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,0DAA0D;IAC1D,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,kHAAkH;AAClH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,cAAc,CAAC;IAAE,YAAY,EAAE,IAAI,CAAA;CAAE,CAAC,CAgCvF;AAED,kEAAkE;AAClE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,iBAAiB,GAAG,OAAO,CAE9E"}

package/dist/ops/position.js

@@ -0,0 +1,73 @@
+import { BuildError } from "../core/errors.js";
+import { clmmCollectFeesGas, clmmLockGas, cpmmCollectFeesGas, cpmmLockGas, } from "../core/gas.js";
+import { randomQueryId } from "../core/tx.js";
+import * as cpmmCodec from "../codec/cpmm.js";
+import * as clmmCodec from "../codec/clmm.js";
+import { pendingFees } from "../math/cpmm.js";
+/** Fees a CPMM position can collect right now. */
+export function cpmmPendingFees(args) {
+    return pendingFees({
+        lp: args.position.lp,
+        feesLp: args.pool.feesLp,
+        checkpoint: args.position.feeCheckpoint,
+    });
+}
+/**
+ * Builds a fee collection. Works on a locked position too: locking stops
+ * withdrawals, not fee income.
+ */
+export function buildCollectFees(args) {
+    if (args.frozen === true) {
+        throw new BuildError('this position is settling a previous operation — try again shortly');
+    }
+    if (args.pending === true) {
+        throw new BuildError('this position is settling a withdrawal or fee collection — try again once it settles');
+    }
+    const queryId = args.queryId ?? randomQueryId();
+    const gas = args.protocol === 'cpmm' ? cpmmCollectFeesGas() : clmmCollectFeesGas();
+    const body = args.protocol === 'cpmm'
+        ? cpmmCodec.encodeWithdrawFees({ queryId })
+        : clmmCodec.encodeWithdrawFees({ queryId });
+    return {
+        txs: [{ to: args.position, value: gas.attach, body }],
+        queryId,
+        details: { protocol: args.protocol },
+        warnings: [],
+    };
+}
+/** The exact phrase `lockForever` requires, so the call cannot be made by accident. */
+export const LOCK_CONFIRMATION = 'lock this liquidity forever';
+/** Builds an irreversible position lock. The liquidity stays in the pool permanently; fees remain collectable. */
+export function buildLockForever(args) {
+    if (args.confirm !== LOCK_CONFIRMATION) {
+        throw new BuildError('locking a position cannot be undone by anyone, ever. ' +
+            `To go ahead, pass confirm: ${JSON.stringify(LOCK_CONFIRMATION)}.`);
+    }
+    if (args.alreadyLocked === true) {
+        throw new BuildError('this position is already locked');
+    }
+    const queryId = args.queryId ?? randomQueryId();
+    const gas = args.protocol === 'cpmm' ? cpmmLockGas() : clmmLockGas();
+    const body = args.protocol === 'cpmm'
+        ? cpmmCodec.encodeLockLiquidity({ queryId })
+        : clmmCodec.encodeLockLiquidity({ queryId });
+    return {
+        txs: [{ to: args.position, value: gas.attach, body }],
+        queryId,
+        details: { irreversible: true },
+        warnings: [
+            'this cannot be undone: the liquidity stays in the pool permanently',
+            'fees can still be collected afterwards',
+            // CPMM has one position per wallet per pool and later deposits merge into it
+            // with the lock kept; CLMM deploys a new position.
+            ...(args.protocol === 'cpmm'
+                ? ['every later deposit from this wallet into this pool merges into this position and is locked too']
+                : []),
+        ],
+    };
+}
+/** Whether a position is locked, from either protocol's state. */
+export function isLocked(state) {
+    return state.locked;
+}
+//# sourceMappingURL=position.js.map

package/dist/ops/position.js.map

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