sally-defi-ts-sdk 0.3.2

package/src/modules/liquidity.ts

@@ -0,0 +1,446 @@
+/**
+ * Liquidity management: add / increase / decrease / remove / lock / harvest,
+ * plus position & pool reads (Sidecar views served through the liq proxy).
+ *
+ * Add-liquidity takes a single struct on-chain; the SDK exposes explicit options
+ * with sane defaults (mins = 0, lockDays = 0, referral = zero, deadline auto) and
+ * auto-approves the ERC-20 sides to the liq proxy before sending.
+ */
+
+import { Contract, getAddress } from "ethers";
+import type { SallyClient } from "../client.js";
+import { ZERO, isNative } from "../token.js";
+import {
+  ClaimableFees,
+  Lock,
+  V2PoolState,
+  V2Position,
+  V3PoolState,
+  V3Position,
+  V4PoolState,
+  V4Position,
+} from "../types.js";
+
+const DEFAULT_DEADLINE_SECS = 1200; // 20 min
+
+type Tx = Record<string, any>;
+type PoolKey = [string, string, number, number, string];
+
+export class Liquidity {
+  private _c: SallyClient;
+  private _liq: Contract;
+  private _side: Contract;
+
+  constructor(client: SallyClient) {
+    this._c = client;
+    this._liq = client.liquidityContract;
+    this._side = client.sidecarContract;
+  }
+
+  // ------------------------------------------------------------------ //
+  // helpers
+  // ------------------------------------------------------------------ //
+  private _a(x: string): string {
+    return getAddress(x);
+  }
+
+  deadline(secs: number = DEFAULT_DEADLINE_SECS): number {
+    return Math.floor(Date.now() / 1000) + secs;
+  }
+
+  /**
+   * Approve each [token, amount] ERC-20 side to the liq proxy.
+   * Returns the native value to attach (sum of any native-token sides).
+   */
+  private async _approveAndValue(pairs: [string, bigint][]): Promise<bigint> {
+    const spender = this._c.addresses["liquidity"];
+    let value = 0n;
+    for (const [token, amount] of pairs) {
+      if (amount <= 0n) continue;
+      if (isNative(token)) {
+        value += amount;
+      } else {
+        await this._c.token(token).ensureAllowance(spender, amount);
+      }
+    }
+    return value;
+  }
+
+  // ------------------------------------------------------------------ //
+  // add liquidity
+  // ------------------------------------------------------------------ //
+  async addV2(
+    dexId: number,
+    tokenA: string,
+    tokenB: string,
+    amountA: bigint,
+    amountB: bigint,
+    opts: {
+      amountAMin?: bigint;
+      amountBMin?: bigint;
+      lockDays?: number;
+      referral?: string;
+      deadline?: number | null;
+      approve?: boolean;
+      tx?: Tx;
+    } = {},
+  ): Promise<any> {
+    tokenA = this._a(tokenA);
+    tokenB = this._a(tokenB);
+    const approve = opts.approve ?? true;
+    const value = approve ? await this._approveAndValue([[tokenA, amountA], [tokenB, amountB]]) : 0n;
+    const p = [
+      dexId, tokenA, tokenB, amountA, amountB,
+      opts.amountAMin ?? 0n, opts.amountBMin ?? 0n, opts.lockDays ?? 0, this._a(opts.referral ?? ZERO),
+      opts.deadline ?? this.deadline(),
+    ];
+    return this._c.send(this._liq.getFunction("addLiquidityV2"), [p], { value, ...(opts.tx ?? {}) });
+  }
+
+  async addV3(
+    dexId: number,
+    token0: string,
+    token1: string,
+    fee: number,
+    tickLower: number,
+    tickUpper: number,
+    amount0: bigint,
+    amount1: bigint,
+    opts: {
+      amount0Min?: bigint;
+      amount1Min?: bigint;
+      lockDays?: number;
+      referral?: string;
+      deadline?: number | null;
+      approve?: boolean;
+      tx?: Tx;
+    } = {},
+  ): Promise<any> {
+    token0 = this._a(token0);
+    token1 = this._a(token1);
+    const approve = opts.approve ?? true;
+    const value = approve ? await this._approveAndValue([[token0, amount0], [token1, amount1]]) : 0n;
+    const p = [
+      dexId, token0, token1, fee, tickLower, tickUpper,
+      amount0, amount1, opts.amount0Min ?? 0n, opts.amount1Min ?? 0n,
+      opts.lockDays ?? 0, this._a(opts.referral ?? ZERO), opts.deadline ?? this.deadline(),
+    ];
+    return this._c.send(this._liq.getFunction("addLiquidityV3"), [p], { value, ...(opts.tx ?? {}) });
+  }
+
+  /** poolKey = [currency0, currency1, fee, tickSpacing, hooks]. */
+  async addV4(
+    dexId: number,
+    poolKey: PoolKey,
+    tickLower: number,
+    tickUpper: number,
+    liquidity: bigint,
+    amount0Max: bigint,
+    amount1Max: bigint,
+    amount0: bigint,
+    amount1: bigint,
+    opts: {
+      lockDays?: number;
+      referral?: string;
+      deadline?: number | null;
+      approve?: boolean;
+      tx?: Tx;
+    } = {},
+  ): Promise<any> {
+    const c0 = this._a(poolKey[0]);
+    const c1 = this._a(poolKey[1]);
+    const approve = opts.approve ?? true;
+    const value = approve ? await this._approveAndValue([[c0, amount0], [c1, amount1]]) : 0n;
+    const key = [c0, c1, poolKey[2], poolKey[3], this._a(poolKey[4])];
+    const p = [
+      dexId, key, tickLower, tickUpper, liquidity,
+      amount0Max, amount1Max, amount0, amount1,
+      opts.lockDays ?? 0, this._a(opts.referral ?? ZERO), opts.deadline ?? this.deadline(),
+    ];
+    return this._c.send(this._liq.getFunction("addLiquidityV4"), [p], { value, ...(opts.tx ?? {}) });
+  }
+
+  async addSlipstream(
+    dexId: number,
+    token0: string,
+    token1: string,
+    tickSpacing: number,
+    tickLower: number,
+    tickUpper: number,
+    amount0: bigint,
+    amount1: bigint,
+    opts: {
+      amount0Min?: bigint;
+      amount1Min?: bigint;
+      referral?: string;
+      lockDays?: number;
+      deadline?: number | null;
+      sqrtPriceX96?: bigint;
+      approve?: boolean;
+      tx?: Tx;
+    } = {},
+  ): Promise<any> {
+    token0 = this._a(token0);
+    token1 = this._a(token1);
+    const approve = opts.approve ?? true;
+    const value = approve ? await this._approveAndValue([[token0, amount0], [token1, amount1]]) : 0n;
+    const p = [
+      dexId, token0, token1, tickSpacing, tickLower, tickUpper,
+      amount0, amount1, opts.amount0Min ?? 0n, opts.amount1Min ?? 0n, this._a(opts.referral ?? ZERO),
+      opts.lockDays ?? 0, opts.deadline ?? this.deadline(), opts.sqrtPriceX96 ?? 0n,
+    ];
+    return this._c.send(this._liq.getFunction("addLiquiditySlipstream"), [p], { value, ...(opts.tx ?? {}) });
+  }
+
+  // ------------------------------------------------------------------ //
+  // increase / decrease / remove
+  // ------------------------------------------------------------------ //
+  async increaseV3(
+    npm: string,
+    tokenId: bigint,
+    amount0: bigint,
+    amount1: bigint,
+    opts: { amount0Min?: bigint; amount1Min?: bigint; deadline?: number | null; referral?: string; tx?: Tx } = {},
+  ): Promise<any> {
+    const fn = this._liq.getFunction("increaseLiquidityV3");
+    return this._c.send(fn, [
+      this._a(npm), tokenId, amount0, amount1, opts.amount0Min ?? 0n, opts.amount1Min ?? 0n,
+      opts.deadline ?? this.deadline(), this._a(opts.referral ?? ZERO),
+    ], opts.tx ?? {});
+  }
+
+  async decreaseV3(
+    npm: string,
+    tokenId: bigint,
+    liquidity: bigint,
+    opts: { amount0Min?: bigint; amount1Min?: bigint; deadline?: number | null; referral?: string; tx?: Tx } = {},
+  ): Promise<any> {
+    const fn = this._liq.getFunction("decreaseLiquidityV3");
+    return this._c.send(fn, [
+      this._a(npm), tokenId, liquidity, opts.amount0Min ?? 0n, opts.amount1Min ?? 0n,
+      opts.deadline ?? this.deadline(), this._a(opts.referral ?? ZERO),
+    ], opts.tx ?? {});
+  }
+
+  async increaseV4(
+    npm: string,
+    tokenId: bigint,
+    liquidity: bigint,
+    amount0Max: bigint,
+    amount1Max: bigint,
+    amount0: bigint,
+    amount1: bigint,
+    opts: { deadline?: number | null; referral?: string; tx?: Tx } = {},
+  ): Promise<any> {
+    const fn = this._liq.getFunction("increaseLiquidityV4");
+    return this._c.send(fn, [
+      this._a(npm), tokenId, liquidity, amount0Max, amount1Max, amount0, amount1,
+      opts.deadline ?? this.deadline(), this._a(opts.referral ?? ZERO),
+    ], opts.tx ?? {});
+  }
+
+  async decreaseV4(
+    npm: string,
+    tokenId: bigint,
+    liquidity: bigint,
+    amount0Min: bigint,
+    amount1Min: bigint,
+    opts: { deadline?: number | null; referral?: string; tx?: Tx } = {},
+  ): Promise<any> {
+    const fn = this._liq.getFunction("decreaseLiquidityV4");
+    return this._c.send(fn, [
+      this._a(npm), tokenId, liquidity, amount0Min, amount1Min,
+      opts.deadline ?? this.deadline(), this._a(opts.referral ?? ZERO),
+    ], opts.tx ?? {});
+  }
+
+  /** Remove V2 LP. `removeLiquidityV2(dexId, tokenA, tokenB, lpAmount, …)`. */
+  async removeV2(
+    dexId: number,
+    tokenA: string,
+    tokenB: string,
+    liquidity: bigint,
+    opts: { amountAMin?: bigint; amountBMin?: bigint; deadline?: number | null; referral?: string; tx?: Tx } = {},
+  ): Promise<any> {
+    const fn = this._liq.getFunction("removeLiquidityV2");
+    return this._c.send(fn, [
+      dexId, this._a(tokenA), this._a(tokenB), liquidity,
+      opts.amountAMin ?? 0n, opts.amountBMin ?? 0n, opts.deadline ?? this.deadline(), this._a(opts.referral ?? ZERO),
+    ], opts.tx ?? {});
+  }
+
+  // ------------------------------------------------------------------ //
+  // locks
+  // ------------------------------------------------------------------ //
+  async lockV2(pair: string, amount: bigint, lockDays: number, tx: Tx = {}): Promise<any> {
+    return this._c.send(this._liq.getFunction("lockV2LP"), [this._a(pair), amount, lockDays], tx);
+  }
+
+  async lockV3(npm: string, tokenId: bigint, lockDays: number, tx: Tx = {}): Promise<any> {
+    return this._c.send(this._liq.getFunction("lockV3Position"), [this._a(npm), tokenId, lockDays], tx);
+  }
+
+  async lockV4(npm: string, tokenId: bigint, lockDays: number, tx: Tx = {}): Promise<any> {
+    return this._c.send(this._liq.getFunction("lockV4Position"), [this._a(npm), tokenId, lockDays], tx);
+  }
+
+  async unlockV2(lockKey: string, tx: Tx = {}): Promise<any> {
+    return this._c.send(this._liq.getFunction("unlockV2"), [lockKey], tx);
+  }
+
+  async unlockV3(npm: string, tokenId: bigint, tx: Tx = {}): Promise<any> {
+    return this._c.send(this._liq.getFunction("unlockV3"), [this._a(npm), tokenId], tx);
+  }
+
+  async unlockV4(npm: string, tokenId: bigint, tx: Tx = {}): Promise<any> {
+    return this._c.send(this._liq.getFunction("unlockV4"), [this._a(npm), tokenId], tx);
+  }
+
+  // ------------------------------------------------------------------ //
+  // claim fees / harvest
+  // ------------------------------------------------------------------ //
+  async claimFeesV3(npm: string, tokenId: bigint, recipient: string | null = null, tx: Tx = {}): Promise<any> {
+    recipient = recipient ?? this._c.requireAddress();
+    return this._c.send(this._liq.getFunction("claimFeesV3"), [this._a(npm), tokenId, this._a(recipient)], tx);
+  }
+
+  async claimFeesV4(npm: string, tokenId: bigint, recipient: string | null = null, tx: Tx = {}): Promise<any> {
+    recipient = recipient ?? this._c.requireAddress();
+    return this._c.send(this._liq.getFunction("claimFeesV4"), [this._a(npm), tokenId, this._a(recipient)], tx);
+  }
+
+  async claimFeesV3Locked(tokenId: bigint, recipient: string, outputToken: string, tx: Tx = {}): Promise<any> {
+    return this._c.send(
+      this._liq.getFunction("claimFeesV3Locked"),
+      [tokenId, this._a(recipient), this._a(outputToken)],
+      tx,
+    );
+  }
+
+  async claimFeesV4Locked(npm: string, tokenId: bigint, recipient: string, tx: Tx = {}): Promise<any> {
+    return this._c.send(this._liq.getFunction("claimFeesV4Locked"), [this._a(npm), tokenId, this._a(recipient)], tx);
+  }
+
+  /** Claim fees from many positions at once into one token. `massClaimFees`. */
+  async massClaimFees(npms: string[], tokenIds: bigint[], outputToken: string, tx: Tx = {}): Promise<any> {
+    return this._c.send(
+      this._liq.getFunction("massClaimFees"),
+      [npms.map((a) => this._a(a)), tokenIds, this._a(outputToken)],
+      tx,
+    );
+  }
+
+  async harvestOp(op: number, data: string, tx: Tx = {}): Promise<any> {
+    return this._c.send(this._liq.getFunction("harvestOp"), [op, data], tx);
+  }
+
+  async claimBatchFees(tokens: string[], tx: Tx = {}): Promise<any> {
+    return this._c.send(this._liq.getFunction("claimBatchFees"), [tokens.map((a) => this._a(a))], tx);
+  }
+
+  async claimReferralFees(tokens: string[], tx: Tx = {}): Promise<any> {
+    return this._c.send(this._liq.getFunction("claimReferralFees"), [tokens.map((a) => this._a(a))], tx);
+  }
+
+  // ------------------------------------------------------------------ //
+  // reads (sidecar via liq proxy)
+  // ------------------------------------------------------------------ //
+  async positionsV2(wallet: string, pairs: string[]): Promise<V2Position[]> {
+    const r = await this._c.call(this._side.getFunction("getV2Positions"), [this._a(wallet), pairs.map((p) => this._a(p))]);
+    return [...r].map((x) => V2Position.fromRaw(x));
+  }
+
+  async positionsV3(wallet: string, start = 0, end = 0): Promise<V3Position[]> {
+    const r = await this._c.call(this._side.getFunction("getV3Positions"), [this._a(wallet), start, end]);
+    return [...r].map((x) => V3Position.fromRaw(x));
+  }
+
+  async positionsV4(wallet: string, start = 0, end = 0): Promise<V4Position[]> {
+    const r = await this._c.call(this._side.getFunction("getV4Positions"), [this._a(wallet), start, end]);
+    return [...r].map((x) => V4Position.fromRaw(x));
+  }
+
+  async poolStateV2(pair: string): Promise<V2PoolState> {
+    return V2PoolState.fromRaw(await this._c.call(this._side.getFunction("getV2PoolState"), [this._a(pair)]));
+  }
+
+  async poolStateV3(pool: string): Promise<V3PoolState> {
+    return V3PoolState.fromRaw(await this._c.call(this._side.getFunction("getV3PoolState"), [this._a(pool)]));
+  }
+
+  async poolStateV4(poolKey: PoolKey): Promise<V4PoolState> {
+    const key = [this._a(poolKey[0]), this._a(poolKey[1]), poolKey[2], poolKey[3], this._a(poolKey[4])];
+    return V4PoolState.fromRaw(await this._c.call(this._side.getFunction("getV4PoolState"), [key]));
+  }
+
+  async locks(wallet: string): Promise<Lock[]> {
+    const r = await this._c.call(this._side.getFunction("getLocks"), [this._a(wallet)]);
+    return [...r].map((x) => Lock.fromRaw(x));
+  }
+
+  async lockKeys(wallet: string): Promise<string[]> {
+    const r = await this._c.call(this._liq.getFunction("getLockKeys"), [this._a(wallet)]);
+    return [...r].map((x) => String(x));
+  }
+
+  async claimableFees(npm: string, tokenId: bigint): Promise<ClaimableFees> {
+    return ClaimableFees.fromRaw(await this._c.call(this._side.getFunction("getClaimableFees"), [this._a(npm), tokenId]));
+  }
+
+  /** USD value (1e18) of `amount` of `token`. `usdValue`. */
+  async usdValue(token: string, amount: bigint): Promise<bigint> {
+    return BigInt(await this._c.call(this._side.getFunction("usdValue"), [this._a(token), amount]));
+  }
+
+  // -- state / config reads --------------------------------------------- //
+  async isPaused(): Promise<boolean> {
+    return Boolean(await this._c.call(this._liq.getFunction("paused"), []));
+  }
+
+  async totalLockedLp(pair: string): Promise<bigint> {
+    return BigInt(await this._c.call(this._liq.getFunction("totalLockedLp"), [this._a(pair)]));
+  }
+
+  /** Current V2 lock nonce of a wallet (input to {@link removeV2}). */
+  async v2LockNonce(wallet: string): Promise<bigint> {
+    return BigInt(await this._c.call(this._liq.getFunction("v2LockNonce"), [this._a(wallet)]));
+  }
+
+  async priceOracle(): Promise<string> {
+    return String(await this._c.call(this._liq.getFunction("priceOracle"), []));
+  }
+
+  /** Harvest/op fee split. `getOpFee(amount) -> [fee, net]`. */
+  async opFee(amount: bigint): Promise<[bigint, bigint]> {
+    const r = await this._c.call(this._liq.getFunction("getOpFee"), [amount]);
+    return [BigInt(r[0]), BigInt(r[1])];
+  }
+
+  async minLockDays(): Promise<number> {
+    return Number(await this._c.call(this._liq.getFunction("MIN_LOCK_DAYS"), []));
+  }
+
+  async maxLocksPerOwner(): Promise<number> {
+    return Number(await this._c.call(this._liq.getFunction("MAX_LOCKS_PER_OWNER"), []));
+  }
+
+  // -- dex registry ------------------------------------------------------ //
+  async dexCount(version: number): Promise<number> {
+    const name = { 2: "v2DexCount", 3: "v3DexCount", 4: "v4DexCount" }[version];
+    return Number(await this._c.call(this._liq.getFunction(name!), []));
+  }
+
+  async dex(version: number, index: number): Promise<any[]> {
+    const name = { 2: "v2Dexes", 3: "v3Dexes", 4: "v4Dexes" }[version];
+    const r = await this._c.call(this._liq.getFunction(name!), [index]);
+    return [...r];
+  }
+
+  /** All registered DEXes for a version (name, router/factory, …, enabled). */
+  async dexes(version: number): Promise<any[][]> {
+    const n = await this.dexCount(version);
+    const out: any[][] = [];
+    for (let i = 0; i < n; i++) out.push(await this.dex(version, i));
+    return out;
+  }
+}

package/src/modules/prices.ts

@@ -0,0 +1,97 @@
+/**
+ * Pricing & token-safety reads (Lens views via the swap proxy).
+ *
+ * v2.0.2 pricing model:
+ *
+ * - {@link Prices.usd} — `getUsdPrice` = **spot-mid**, for *display*.
+ * - {@link Prices.usdImpact} — `getUsdPriceImpact` = **execution-aware** realised
+ *   price, for quotes / slippage math.
+ * - {@link Prices.spot} — `getSpotPrice(tokenIn, tokenOut)`, raw mid between two tokens.
+ */
+
+import { Contract, getAddress } from "ethers";
+import type { SallyClient } from "../client.js";
+import { PriceResult, TokenInfo } from "../types.js";
+import { SafetyConfig } from "../safety.js";
+import { ZERO } from "../token.js";
+
+export class Prices {
+  private _c: SallyClient;
+  private _lens: Contract;
+
+  constructor(client: SallyClient) {
+    this._c = client;
+    this._lens = client.lensContract;
+  }
+
+  private _addr(a: string): string {
+    return getAddress(a);
+  }
+
+  // -- USD pricing ------------------------------------------------------- //
+  /** Spot-mid USD price (1e18) — for display. `getUsdPrice`. */
+  async usd(token: string): Promise<PriceResult> {
+    const r = await this._c.call(this._lens.getFunction("getUsdPrice"), [this._addr(token)]);
+    return PriceResult.fromRaw(r);
+  }
+
+  /** Execution-aware USD price (1e18) — for quotes. `getUsdPriceImpact`. */
+  async usdImpact(token: string): Promise<PriceResult> {
+    const r = await this._c.call(this._lens.getFunction("getUsdPriceImpact"), [this._addr(token)]);
+    return PriceResult.fromRaw(r);
+  }
+
+  /** Price denominated in WETH (1e18). `getWethPrice`. */
+  async weth(token: string): Promise<PriceResult> {
+    const r = await this._c.call(this._lens.getFunction("getWethPrice"), [this._addr(token)]);
+    return PriceResult.fromRaw(r);
+  }
+
+  /**
+   * Raw spot mid-price of `tokenIn` in `tokenOut` (1e18).
+   *
+   * `getSpotPrice(tokenIn, tokenOut)`.
+   */
+  async spot(tokenIn: string, tokenOut: string): Promise<bigint> {
+    return BigInt(
+      await this._c.call(this._lens.getFunction("getSpotPrice"), [this._addr(tokenIn), this._addr(tokenOut)]),
+    );
+  }
+
+  // -- USD liquidity ----------------------------------------------------- //
+  /**
+   * Aggregate USD liquidity behind a token (1e18).
+   *
+   * `version` in {2,3,4} targets a single DEX generation; `null`/`undefined` sums all.
+   */
+  async usdLiquidity(token: string, version: number | null = null): Promise<bigint> {
+    const a = this._addr(token);
+    const name = {
+      null: "getUsdLiquidity",
+      2: "getUsdLiquidityV2",
+      3: "getUsdLiquidityV3",
+      4: "getUsdLiquidityV4",
+    }[version === null ? "null" : version];
+    return BigInt(await this._c.call(this._lens.getFunction(name!), [a]));
+  }
+
+  // -- token safety ------------------------------------------------------ //
+  /**
+   * Honeypot / buy-sell-tax round-trip probe. `getTokenInfos`.
+   *
+   * The on-chain probe only runs with `tx.origin == 0` and a native probe
+   * balance, so this is called with `from = 0x0` and `probeValue` attached —
+   * anything else returns all-zero.
+   */
+  async tokenInfo(token: string, opts: { probeValue?: bigint | null } = {}): Promise<TokenInfo> {
+    let probeValue = opts.probeValue ?? null;
+    if (probeValue === null) {
+      probeValue = new SafetyConfig().probeValue;
+    }
+    const r = await this._lens.getFunction("getTokenInfos").staticCall(this._addr(token), {
+      from: ZERO,
+      value: probeValue,
+    });
+    return TokenInfo.fromRaw(r);
+  }
+}