lpsignal 0.9.0 → 0.11.0

package/README.md

@@ -104,6 +104,85 @@ app.post('/lpsignal', express.raw({ type: 'application/json' }), (req, res) => {
 Pass the raw body (a `Buffer` or string), never re-serialised JSON. Deliveries older than 5 minutes are rejected
 (`toleranceSec`); every retry is signed afresh.
 
+## Adding and removing liquidity
+
+`lpsignal/liquidity` builds the transactions to add liquidity to a pool (in the range you choose) and to remove it,
+on the pools' official position managers — Uniswap v3, PancakeSwap v3, Aerodrome and Velodrome Slipstream. You sign
+and send them with your own [viem](https://viem.sh) wallet: your keys never reach the SDK, the position is always minted
+to and collected by your own address, and there is no LPSignal contract or fee in between. Uniswap v4 pools are not
+supported here (use the Uniswap app). Install viem next to the SDK: `npm i lpsignal viem`.
+
+```js
+import { LPSignal } from 'lpsignal';
+import { planAddLiquidity, planRemoveLiquidity, positions, sendPlan } from 'lpsignal/liquidity';
+import { createPublicClient, createWalletClient, http, parseEther } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { base } from 'viem/chains';
+
+const account = privateKeyToAccount(process.env.PRIVATE_KEY);
+const publicClient = createPublicClient({ chain: base, transport: http() });
+const wallet = createWalletClient({ account, chain: base, transport: http() });
+
+// the pool's tokens, decimals, fee and tick spacing
+const { pool } = await new LPSignal().pool('base', '0x6c561b446416e1a00e8e93e221854d6ea4171372');
+// ±5% around the current price, 1 WETH in, paid in ETH; the USDC side is computed
+const plan = await planAddLiquidity(publicClient, pool, { owner: account.address, amount0: parseEther('1'), rangeBp: 500, nativeSide: 0 });
+await sendPlan(wallet, publicClient, [...plan.approvals, plan.mint]); // exact approvals, then the mint
+
+// later: your positions, then take half of one out (principal + fees, to you)
+const [pos] = (await positions(publicClient, 'base', account.address)).filter((p) => p.pool === pool.address);
+const half = await planRemoveLiquidity(publicClient, pos, { owner: account.address, shareBps: 5000 });
+// finalized: wait until that block is final before taking more from the same position (a reorg could otherwise drop
+// this removal while the next one reads the old liquidity, and both land)
+const [{ blockNumber }] = await sendPlan(wallet, publicClient, [half.call], { finalized: true });
+// the rest: read at a block no older than that removal
+const rest = await planRemoveLiquidity(publicClient, pos, { owner: account.address, shareBps: 10000, minBlock: blockNumber });
+await sendPlan(wallet, publicClient, [rest.call]);
+```
+
+- Minimum amounts follow the Uniswap SDK's rule for a price move of up to `slippageBps` (default 0.5%); transactions
+  expire after `deadlineS` (default 20 minutes).
+- Every planned call is bound to its chain and owner: `sendPlan` refuses to send it from another account or chain.
+- `sendPlan` waits for each receipt. If one is not seen in time it throws `TxPending` with the hash: **do not send the
+  same mint or partial removal again until you know what became of it** — a second one would also go through. A
+  transaction cancelled or replaced in the wallet throws `TxReplaced` and stops the plan (a speed-up is fine). A send
+  that fails without a hash throws `TxUnknown` with the account and the nonce it was sent with: check whether that nonce
+  was used first (with a nonce manager or a wallet that picks nonces itself, check its history). Plans of one account
+  are sent one after another within a process; do not send from the same account elsewhere at the same time. After a
+  `TxUnknown`, `TxPending` or `TxReplaced`, every further send from that account on that chain throws `AccountBlocked` until you have
+  checked the transaction and call `unblock(chainId, account)`.
+- Minimum amounts are what the position manager would take at the edges of the `slippage` band. With a range narrower
+  than that band (e.g. ±0.05% on a stable pair at 0.5% slippage) both minimums can be 0: the mint then has no on-chain
+  price bound, but a price pushed outside your range only makes the deposit single-sided (a mint never trades), and
+  coming back it converts at prices inside your range — the loss is bounded by the range's width.
+- Positions staked in an Aerodrome / Velodrome gauge belong to the gauge and are not listed by `positions`.
+- Not financial advice: a range that paid well can lose money if the price leaves it.
+
+## Swapping
+
+`planSwap` swaps one of a pool's tokens for the other (e.g. the side you are short of before adding) through the
+[KyberSwap](https://kyberswap.com) aggregator, with **LPSignal's fee: 0.25% of the input (0.05% in stable pools)**,
+sent by the aggregator's router to LPSignal's address. The aggregator's answers are checked, never trusted: the quote
+must be close to the pool's own on-chain price, and the transaction it builds is decoded — the router, the tokens and
+amount, the recipient (your own address), exactly LPSignal's fee and no other, no permit, and a guaranteed minimum out
+no lower than your slippage allows — then simulated. The router pays at least `minReturn` or the swap reverts.
+
+```js
+import { planSwap, sendPlan } from 'lpsignal/liquidity';
+// 0.1 ETH (paid as the native coin) for USDC in the WETH/USDC pool
+const swap = await planSwap(publicClient, pool, { owner: account.address, fromSide: 0, fromNative: true, amountIn: parseEther('0.1') });
+console.log(swap.quoteOut, swap.minReturn, swap.feeBps);
+await sendPlan(wallet, publicClient, [...swap.approvals, swap.swap]); // an exact approval if needed, then the swap
+```
+
+- `minOut`: the least the swap must deliver (e.g. what you are short of); refused (`SwapRefused` `moved`) if the quote
+  less the slippage no longer covers it. Other refusals: `impact` (the quote is too far under the pool price),
+  `quote` / `calldata` (the aggregator's answer did not match), `simulation` (it would revert now).
+- Send the plan right away (quotes move; it expires after `deadlineS`, default 10 minutes). A swap's deadline sits in
+  calldata nobody can check, so after a `TxUnknown` / `TxPending` find out what became of that very transaction before
+  swapping again (`sendPlan` blocks the account meanwhile).
+- Uniswap v4 pools are not supported. The aggregator refuses some addresses (e.g. well-known test keys).
+
 ## License
 
 MIT

package/README.zh.md

@@ -71,6 +71,33 @@ await lps.createRule({ kind: 'depeg', name: 'early depeg', minDeviation: 0.003 }
 await lps.setSubscriptions(['net_apr', 'burst', 'depeg']); // 推送哪些类型（规则命中总会推送）
 ```
 
+## 添加和移除流动性
+
+`lpsignal/liquidity` 负责构造交易：在你选的价格区间内添加流动性，以及移除流动性。交易发到池子的官方仓位合约（Uniswap v3、PancakeSwap v3、Aerodrome 和 Velodrome Slipstream）。签名和发送都用你自己的 [viem](https://viem.sh) 钱包：私钥不经过 SDK；仓位只会创建到你自己的地址，资金也只领回到你自己的地址；中间没有 LPSignal 的合约，也不收费。这里不支持 Uniswap v4 池子（请用 Uniswap 官方应用）。需要和 SDK 一起安装 viem：`npm i lpsignal viem`。
+
+用法见英文 README 的示例：`planAddLiquidity` → `sendPlan`，`positions` → `planRemoveLiquidity` → `sendPlan`。
+
+- 最低成交量按 Uniswap SDK 的规则计算，允许的价格变动由 `slippageBps` 指定（默认 0.5%）；交易在 `deadlineS` 之后失效（默认 20 分钟）。
+- `sendPlan` 会等每一笔的回执。如果规定时间内没等到，会抛出带交易哈希的 `TxPending`：**在弄清楚这笔交易的结果之前，不要重发同一笔创建仓位或部分移除的交易**，否则第二笔也会成交。
+- 每笔计划好的交易都绑定了所属的链和账户：从别的账户或别的链发送，`sendPlan` 会拒绝。在钱包里被取消或替换成别的交易时，会抛出 `TxReplaced` 并停止整个计划（只是加速则没关系）。
+- 发送时出错且拿不到交易哈希（节点可能已经收下了这笔交易）会抛出 `TxUnknown`，带上账户和 nonce：请先确认这个 nonce 有没有被用掉，再决定是否重发。
+- 出现 `TxUnknown`、`TxPending` 或 `TxReplaced` 后，这个账户在这条链上的后续发送都会抛出 `AccountBlocked`，直到你核实那笔交易后调用 `unblock(chainId, account)`。
+- 对同一个仓位做下一次部分移除前，给 `sendPlan` 传 `{ finalized: true }`，等那个区块最终确认后再继续，避免链重组导致多取。
+- 对同一个仓位做下一次移除时，把上一次 `sendPlan` 返回的区块号作为 `minBlock` 传入，这样 SDK 只会在不旧于那个区块的数据上计算，不会因为 RPC 节点落后而多取。
+- 最低成交量是价格在滑点范围两端时、仓位合约实际会收取的数量。如果区间比滑点范围还窄（例如稳定币池 ±0.05% 区间配 0.5% 滑点），两个最低值都可能是 0，这时交易在链上没有价格限制。但价格被推出你的区间时，添加只会变成存入单一代币（添加本身不做兑换）；价格回来时，转换只发生在你的区间内，所以损失上限是区间的宽度。
+- 质押在 Aerodrome / Velodrome gauge 里的仓位属于 gauge，`positions` 不会列出。
+- 不构成投资建议：过去收益好的区间，价格离开后也可能亏损。
+
+## 兑换
+
+`planSwap` 通过 [KyberSwap](https://kyberswap.com) 聚合器，把池子里的一种代币兑换成另一种（例如添加前补足不够的那一边）。**LPSignal 收取输入金额的 0.25%（稳定型池 0.05%）作为手续费**，由聚合器路由合约直接转到 LPSignal 的地址。聚合器的返回不会被直接信任：报价必须接近池子自身的链上价格；它构造的交易会被解码核对，包括路由合约、代币和数量、收款人（你自己的地址）、手续费恰好是 LPSignal 的且没有其他费用、没有 permit、保证的最少到账不低于你的滑点允许值，然后再模拟一次。路由合约保证至少到账 `minReturn`，否则交易回滚。
+
+用法：`planSwap(publicClient, pool, { owner, fromSide, amountIn, fromNative?, toNative?, slippageBps?, minOut? })` → `sendPlan(wallet, publicClient, [...plan.approvals, plan.swap])`。
+
+- `minOut`：这次兑换至少要到账的数量（例如你缺的数量）；报价扣除滑点后不够时会拒绝（`SwapRefused` `moved`）。其他拒绝原因：`impact`（报价比池子价格低太多）、`quote` / `calldata`（聚合器返回与请求不符）、`simulation`（现在发送会失败）。
+- 计划生成后请立即发送（报价会变；`deadlineS` 后失效，默认 10 分钟）。兑换的截止时间写在无法核对的 calldata 里，所以遇到 `TxUnknown` / `TxPending` 后，请先弄清那笔交易本身的结果再兑换（期间 `sendPlan` 会锁住该账户）。
+- 不支持 Uniswap v4 池子。聚合器会拒绝部分地址（例如公开的测试私钥）。
+
 ## 开发
 
 ```bash

package/dist/liquidity/core.d.ts

@@ -0,0 +1,361 @@
+/**
+ * Concentrated-liquidity math and the official position-manager calls (Uniswap v3 / PancakeSwap v3
+ * NonfungiblePositionManager, Aerodrome / Velodrome Slipstream) — the same code the lpsignal.app web app runs, kept in
+ * step with it. Pure: nothing here signs or sends; recipients are always the caller's own address.
+ *
+ * Math is the pools' own, in integers: TickMath.getSqrtRatioAtTick, LiquidityAmounts, SqrtPriceMath (rounding as the
+ * contracts do), and the Uniswap SDK's slippage rule for the minimum amounts.
+ */
+import { type Address, type Hex } from 'viem';
+export type LpDex = 'uniswap_v3' | 'pancake_v3' | 'aerodrome_cl' | 'velodrome_cl';
+/** position managers per chain and dex — the ones whose factory created the pools we track (src/chains.ts `npms`) */
+export declare const NPM: Record<string, Partial<Record<LpDex, Address>>>;
+export declare const CHAIN_ID: Record<string, number>;
+/** the wrapped native coin the position managers wrap msg.value into (their WETH9()) */
+export declare const WRAPPED: Record<string, Address>;
+export declare const EXPLORER: Record<string, string>;
+export declare const NATIVE_SYMBOL: Record<string, string>;
+/** USDT on Ethereum refuses to change a non-zero allowance to another non-zero one: reset it to 0 first */
+export declare const ZERO_FIRST: Record<string, Address[]>;
+export declare const isSlipstream: (dex: string) => boolean;
+export declare function npmOf(chain: string, dex: string): Address | null;
+export declare const MIN_TICK = -887272;
+export declare const MAX_TICK = 887272;
+export declare const MIN_SQRT_RATIO = 4295128739n;
+export declare const MAX_SQRT_RATIO = 1461446703485210103287273052203988822378723970342n;
+export declare function sqrtRatioAtTick(tick: number): bigint;
+/** the full range: the extreme ticks rounded inward to the spacing (the widest legal position) */
+export declare function fullRange(tickSpacing: number): [number, number];
+/** ±rangeBp of price around `tick`, widened outward to the tick grid, always containing the price (0 = full range) — as the backtests */
+export declare function rangeTicks(tick: number, rangeBp: number, tickSpacing: number): [number, number];
+/** the liquidity the position manager mints for these desired amounts (LiquidityAmounts.getLiquidityForAmounts) */
+export declare function liquidityForAmounts(sp: bigint, sa: bigint, sb: bigint, amount0: bigint, amount1: bigint): bigint;
+/** the token amounts liquidity `l` takes at price `sp` (rounded up = what a mint pulls; down = what it is worth) */
+export declare function amountsForLiquidity(sp: bigint, sa: bigint, sb: bigint, l: bigint, up: boolean): [bigint, bigint];
+/**
+ * Given one side's amount, the other side the range needs at the current price (0 when the range takes only one
+ * token at this price; null when the given side is not used at all there).
+ */
+export declare function otherAmount(side: 0 | 1, amount: bigint, sp: bigint, tickLower: number, tickUpper: number): bigint | null;
+/** which tokens a range takes at this price */
+export declare function sidesUsed(sp: bigint, tickLower: number, tickUpper: number): {
+    token0: boolean;
+    token1: boolean;
+};
+export interface MintAmounts {
+    liquidity: bigint;
+    amount0Desired: bigint;
+    amount1Desired: bigint;
+    amount0Min: bigint;
+    amount1Min: bigint;
+}
+/**
+ * The amounts to send for these desired amounts, and the minimums under a price move of up to `slippageBps` before the
+ * transaction lands. The position manager re-derives the liquidity from the desired amounts AT THE PRICE IT MEETS, so
+ * the minimum of each token is what it would actually take at the worse end of the band — token0 at the upper price,
+ * token1 at the lower (each is monotonic in the price) — never the liquidity fixed now valued there (that is higher
+ * than what a moved price takes, and would revert a move well inside the tolerance).
+ */
+export declare function mintAmounts(sp: bigint, tickLower: number, tickUpper: number, desired0: bigint, desired1: bigint, slippageBps: number): MintAmounts;
+export declare const ERC20: readonly [{
+    readonly type: "function";
+    readonly name: "approve";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "allowance";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly name: "spender";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "balanceOf";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}];
+/** the first two fields of slot0 — the same on Uniswap v3, PancakeSwap v3 and Slipstream (the rest differ) */
+export declare const SLOT0: readonly [{
+    readonly type: "function";
+    readonly name: "slot0";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "sqrtPriceX96";
+        readonly type: "uint160";
+    }, {
+        readonly name: "tick";
+        readonly type: "int24";
+    }];
+}];
+export interface Call {
+    to: Address;
+    data: Hex;
+    value: bigint;
+}
+export interface MintInput {
+    chain: string;
+    dex: string;
+    token0: Address;
+    token1: Address;
+    fee: number;
+    tickSpacing: number;
+    tickLower: number;
+    tickUpper: number;
+    amounts: MintAmounts;
+    recipient: Address;
+    deadline: bigint;
+    /** pay this side in the native coin (it must be the wrapped native token): sent as value, the change refunded */
+    nativeSide: 0 | 1 | null;
+}
+/** the mint transaction (with the native coin: multicall(mint, refundETH) carrying the value) */
+export declare function mintCall(m: MintInput): Call;
+export declare function approveCall(token: Address, spender: Address, amount: bigint): Call;
+/** the approvals a mint needs, given the current allowances (exact amounts, never unlimited) */
+export declare function approvalsNeeded(chain: string, npm: Address, needs: {
+    token: Address;
+    amount: bigint;
+    allowance: bigint;
+}[]): Call[];
+/** token units ⇄ text, exact (no floats) */
+export declare function parseUnits(text: string, decimals: number): bigint | null;
+export declare function formatUnits(v: bigint, decimals: number, maxFrac?: number): string;
+/** human price of token0 in token1 at a tick */
+export declare const priceAtTick: (tick: number, decimals0: number, decimals1: number) => number;
+export interface LpPool {
+    chain: string;
+    dex: string;
+    address: Address;
+    token0: Address;
+    token1: Address;
+    decimals0: number;
+    decimals1: number;
+    fee: number;
+    tickSpacing: number;
+}
+export interface MintPlan {
+    tickLower: number;
+    tickUpper: number;
+    amounts: MintAmounts;
+    approvals: Call[];
+    mint: Call;
+}
+/**
+ * Everything a mint needs, from the pool's live price and what the user wants to put in: the range (±rangeBp around
+ * the price, on the grid), the amounts and minimums, the approvals still missing (for the amounts the user entered,
+ * so a re-plan at a fresh price before the mint never needs another one), and the mint itself.
+ */
+export declare function planMint(pool: LpPool, slot0: {
+    sqrtPriceX96: bigint;
+    tick: number;
+}, input: {
+    rangeBp: number;
+    desired0: bigint;
+    desired1: bigint;
+    slippageBps: number;
+    nativeSide: 0 | 1 | null;
+    recipient: Address;
+    deadline: bigint;
+    allowance0: bigint;
+    allowance1: bigint;
+}): MintPlan;
+/** the position-manager calls for reading and removing a position (the same on Uniswap v3, PancakeSwap v3, Slipstream) */
+export declare const NPM_READ: readonly [{
+    readonly type: "function";
+    readonly name: "balanceOf";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "tokenOfOwnerByIndex";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly name: "index";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "positions";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "nonce";
+        readonly type: "uint96";
+    }, {
+        readonly name: "operator";
+        readonly type: "address";
+    }, {
+        readonly name: "token0";
+        readonly type: "address";
+    }, {
+        readonly name: "token1";
+        readonly type: "address";
+    }, {
+        readonly name: "feeOrSpacing";
+        readonly type: "int24";
+    }, {
+        readonly name: "tickLower";
+        readonly type: "int24";
+    }, {
+        readonly name: "tickUpper";
+        readonly type: "int24";
+    }, {
+        readonly name: "liquidity";
+        readonly type: "uint128";
+    }, {
+        readonly name: "feeGrowthInside0LastX128";
+        readonly type: "uint256";
+    }, {
+        readonly name: "feeGrowthInside1LastX128";
+        readonly type: "uint256";
+    }, {
+        readonly name: "tokensOwed0";
+        readonly type: "uint128";
+    }, {
+        readonly name: "tokensOwed1";
+        readonly type: "uint128";
+    }];
+}];
+export declare const COLLECT_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "decreaseLiquidity";
+    readonly stateMutability: "payable";
+    readonly inputs: readonly [{
+        readonly name: "params";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "tokenId";
+            readonly type: "uint256";
+        }, {
+            readonly name: "liquidity";
+            readonly type: "uint128";
+        }, {
+            readonly name: "amount0Min";
+            readonly type: "uint256";
+        }, {
+            readonly name: "amount1Min";
+            readonly type: "uint256";
+        }, {
+            readonly name: "deadline";
+            readonly type: "uint256";
+        }];
+    }];
+    readonly outputs: readonly [{
+        readonly name: "amount0";
+        readonly type: "uint256";
+    }, {
+        readonly name: "amount1";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "collect";
+    readonly stateMutability: "payable";
+    readonly inputs: readonly [{
+        readonly name: "params";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "tokenId";
+            readonly type: "uint256";
+        }, {
+            readonly name: "recipient";
+            readonly type: "address";
+        }, {
+            readonly name: "amount0Max";
+            readonly type: "uint128";
+        }, {
+            readonly name: "amount1Max";
+            readonly type: "uint128";
+        }];
+    }];
+    readonly outputs: readonly [{
+        readonly name: "amount0";
+        readonly type: "uint256";
+    }, {
+        readonly name: "amount1";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "multicall";
+    readonly stateMutability: "payable";
+    readonly inputs: readonly [{
+        readonly name: "data";
+        readonly type: "bytes[]";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "results";
+        readonly type: "bytes[]";
+    }];
+}];
+export interface Position {
+    tokenId: bigint;
+    token0: Address;
+    token1: Address;
+    feeOrSpacing: number;
+    tickLower: number;
+    tickUpper: number;
+    liquidity: bigint;
+}
+/** whether a position belongs to this pool (same tokens and fee — Slipstream: tick spacing) */
+export declare function inPool(pos: Position, pool: LpPool): boolean;
+/**
+ * Taking `share` (basis points of the position, 1..10000) out: the liquidity, what it is worth now, and the minimums
+ * under a price move of up to `slippageBps` (each token at its worse price, as the Uniswap SDK's burn rule).
+ */
+export declare function removeAmounts(sp: bigint, pos: Position, shareBps: number, slippageBps: number): {
+    liquidity: bigint;
+    amount0: bigint;
+    amount1: bigint;
+    amount0Min: bigint;
+    amount1Min: bigint;
+};
+/** collect everything owed (fees + what was decreased) to the wallet — the same call simulated shows the uncollected fees */
+export declare function collectCall(chain: string, dex: string, tokenId: bigint, recipient: Address): Call;
+/**
+ * One transaction: decrease the liquidity (with minimums and a deadline), then collect it all — principal and fees —
+ * to the wallet itself. `liquidity` 0 = fees only (collect).
+ */
+export declare function removeCall(chain: string, dex: string, tokenId: bigint, amounts: {
+    liquidity: bigint;
+    amount0Min: bigint;
+    amount1Min: bigint;
+}, recipient: Address, deadline: bigint): Call;