sally-defi-ts-sdk 0.3.2

package/src/types.ts

@@ -0,0 +1,438 @@
+/**
+ * Typed result objects for every Sally tuple/struct return.
+ *
+ * ethers decodes Solidity structs into positional `Result` arrays. These classes
+ * give each field a name, so callers get `pos.liquidity` instead of `pos[7]` —
+ * and AI/agent callers get a stable, documented schema. Every class has a
+ * `fromRaw` constructor that maps the ABI component order to named fields.
+ *
+ * Amounts are kept as raw `bigint` (wei / token base units). Use
+ * {@link TokenAmount} or the `prices` helpers to humanize.
+ */
+
+import { pyRound } from "./util.js";
+
+// --------------------------------------------------------------------------- //
+// Enums
+// --------------------------------------------------------------------------- //
+/** DEX generation used for a swap hop (matches contract `version` uint8). */
+export enum PoolVersion {
+  V2 = 2,
+  V3 = 3,
+  V4 = 4,
+}
+
+/**
+ * Lock asset kind as stored by the LiquidityController.
+ *
+ * Values match the on-chain constants
+ * (`LOCK_KIND_V3_NFT=1`, `LOCK_KIND_V2_LP=2`, `LOCK_KIND_V4_NFT=3`).
+ */
+export enum LockKind {
+  V3_POSITION = 1,
+  V2_LP = 2,
+  V4_POSITION = 3,
+}
+
+type Raw = readonly any[];
+
+const NATIVE_SENTINELS = new Set([
+  "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
+  "0x0000000000000000000000000000000000000000",
+]);
+
+// --------------------------------------------------------------------------- //
+// Swap routing
+// --------------------------------------------------------------------------- //
+/** One hop of a hybrid route (can itself be multi-token within a version). */
+export class SwapStep {
+  constructor(
+    public readonly version: number,
+    public readonly path: string[],
+    public readonly dexPath: number[],
+    public readonly pools: string[],
+    public readonly baseToken: string,
+    public readonly estimatedAmountOut: bigint,
+  ) {}
+
+  static fromRaw(r: Raw): SwapStep {
+    return new SwapStep(
+      Number(r[0]),
+      [...r[1]].map((a) => String(a)),
+      [...r[2]].map((x) => Number(x)),
+      [...r[3]].map((a) => String(a)),
+      String(r[4]),
+      BigInt(r[5]),
+    );
+  }
+
+  get isEmpty(): boolean {
+    return this.version === 0 && this.path.length === 0;
+  }
+
+  /** ABI-encodable tuple for this step. */
+  toTuple(): [number, string[], number[], string[], string, bigint] {
+    return [this.version, this.path, this.dexPath, this.pools, this.baseToken, this.estimatedAmountOut];
+  }
+}
+
+/**
+ * Result of `getBestSwapPath` — up to three cross-version steps.
+ *
+ * This is exactly the struct `executeHybridSwap` consumes, so it round-trips:
+ * quote -> {@link toTuple} -> execute.
+ */
+export class SwapPath {
+  constructor(
+    public readonly firstStep: SwapStep,
+    public readonly secondStep: SwapStep,
+    public readonly thirdStep: SwapStep,
+    public readonly stepCount: number,
+  ) {}
+
+  static fromRaw(r: Raw): SwapPath {
+    return new SwapPath(
+      SwapStep.fromRaw(r[0]),
+      SwapStep.fromRaw(r[1]),
+      SwapStep.fromRaw(r[2]),
+      Number(r[3]),
+    );
+  }
+
+  /** ABI-encodable tuple for `executeHybridSwap(swapData, …)`. */
+  toTuple(): [ReturnType<SwapStep["toTuple"]>, ReturnType<SwapStep["toTuple"]>, ReturnType<SwapStep["toTuple"]>, number] {
+    return [this.firstStep.toTuple(), this.secondStep.toTuple(), this.thirdStep.toTuple(), this.stepCount];
+  }
+
+  get activeSteps(): SwapStep[] {
+    return [this.firstStep, this.secondStep, this.thirdStep].slice(0, this.stepCount);
+  }
+
+  /** Quoted output = the last active step's estimate. */
+  get estimatedAmountOut(): bigint {
+    const steps = this.activeSteps;
+    return steps.length ? steps[steps.length - 1].estimatedAmountOut : 0n;
+  }
+
+  /** Every pool this route would route through (across all active steps). */
+  get poolAddresses(): string[] {
+    const out: string[] = [];
+    for (const st of this.activeSteps) out.push(...st.pools);
+    return out;
+  }
+
+  /**
+   * Return a list of route-integrity violations (empty == sound route).
+   *
+   * Guards against funds entering the wrong pool: verifies the path starts at
+   * `tokenIn`, ends at `tokenOut` and that every hop chains into the next
+   * (`step[i]` last token == `step[i+1]` first token). Native sentinels are
+   * resolved to `wnative` before comparing.
+   */
+  checkIntegrity(tokenIn: string, tokenOut: string, wnative?: string | null): string[] {
+    const norm = (a: string): string => {
+      a = a.toLowerCase();
+      if (wnative && NATIVE_SENTINELS.has(a)) return wnative.toLowerCase();
+      return a;
+    };
+
+    const problems: string[] = [];
+    const steps = this.activeSteps;
+    if (steps.length === 0) return ["empty route (step_count == 0)"];
+
+    // Chain over the steps that actually carry a token path. Anchoring the
+    // start/end and hop-continuity checks to this list (instead of raw steps)
+    // means an empty intermediate/edge step can't silently drop a link.
+    const chain = steps.filter((s) => s.path.length > 0);
+    if (chain.length === 0) return ["route has no token path"];
+
+    if (norm(chain[0].path[0]) !== norm(tokenIn)) {
+      problems.push(`path start ${chain[0].path[0]} != token_in ${tokenIn}`);
+    }
+    const last = chain[chain.length - 1];
+    if (norm(last.path[last.path.length - 1]) !== norm(tokenOut)) {
+      problems.push(`path end ${last.path[last.path.length - 1]} != token_out ${tokenOut}`);
+    }
+    for (let i = 0; i < chain.length - 1; i++) {
+      const a = chain[i].path[chain[i].path.length - 1];
+      const b = chain[i + 1].path[0];
+      if (norm(a) !== norm(b)) {
+        problems.push(`hop ${i}->${i + 1} broken: ${a} != ${b}`);
+      }
+    }
+    return problems;
+  }
+}
+
+// --------------------------------------------------------------------------- //
+// Token safety / pricing
+// --------------------------------------------------------------------------- //
+/** Honeypot / transfer-tax probe from `getTokenInfos`. */
+export class TokenInfo {
+  constructor(
+    public readonly buyEstimate: bigint,
+    public readonly buyResult: bigint,
+    public readonly sellEstimate: bigint,
+    public readonly sellResult: bigint,
+    public readonly buySuccess: boolean,
+    public readonly approveSuccess: boolean,
+    public readonly sellSuccess: boolean,
+  ) {}
+
+  static fromRaw(r: Raw): TokenInfo {
+    return new TokenInfo(
+      BigInt(r[0]), BigInt(r[1]), BigInt(r[2]), BigInt(r[3]),
+      Boolean(r[4]), Boolean(r[5]), Boolean(r[6]),
+    );
+  }
+
+  /** True if the sell leg failed while the buy succeeded. */
+  get isHoneypot(): boolean {
+    return this.buySuccess && !this.sellSuccess;
+  }
+
+  get buyTaxBps(): number {
+    if (this.buyEstimate === 0n) return 0;
+    return Math.max(0, pyRound((1 - Number(this.buyResult) / Number(this.buyEstimate)) * 10_000));
+  }
+
+  get sellTaxBps(): number {
+    if (this.sellEstimate === 0n) return 0;
+    return Math.max(0, pyRound((1 - Number(this.sellResult) / Number(this.sellEstimate)) * 10_000));
+  }
+}
+
+/** A USD/WETH price (1e18-scaled) plus the base token it was priced via. */
+export class PriceResult {
+  constructor(public readonly price: bigint, public readonly viaToken: string) {}
+
+  static fromRaw(r: Raw): PriceResult {
+    return new PriceResult(BigInt(r[0]), String(r[1]));
+  }
+
+  get asFloat(): number {
+    return Number(this.price) / 1e18;
+  }
+}
+
+/** One entry of `getWalletBalance` — balance + live USD valuation. */
+export class WalletBalance {
+  constructor(
+    public readonly token: string,
+    public readonly balance: bigint,
+    public readonly usdPrice18: bigint,
+    public readonly usdValue: bigint,
+    public readonly decimals: number,
+    public readonly ok: boolean,
+  ) {}
+
+  static fromRaw(r: Raw): WalletBalance {
+    return new WalletBalance(String(r[0]), BigInt(r[1]), BigInt(r[2]), BigInt(r[3]), Number(r[4]), Boolean(r[5]));
+  }
+
+  get balanceFloat(): number {
+    return Number(this.balance) / 10 ** this.decimals;
+  }
+
+  get usdValueFloat(): number {
+    return Number(this.usdValue) / 1e18;
+  }
+}
+
+// --------------------------------------------------------------------------- //
+// Liquidity positions
+// --------------------------------------------------------------------------- //
+export class V2Position {
+  constructor(
+    public readonly pair: string,
+    public readonly token0: string,
+    public readonly token1: string,
+    public readonly lpBalance: bigint,
+    public readonly reserve0: bigint,
+    public readonly reserve1: bigint,
+    public readonly totalSupply: bigint,
+    public readonly share0: bigint,
+    public readonly share1: bigint,
+    public readonly locked: boolean,
+    public readonly unlockTime: bigint,
+  ) {}
+
+  static fromRaw(r: Raw): V2Position {
+    return new V2Position(
+      String(r[0]), String(r[1]), String(r[2]), BigInt(r[3]), BigInt(r[4]), BigInt(r[5]),
+      BigInt(r[6]), BigInt(r[7]), BigInt(r[8]), Boolean(r[9]), BigInt(r[10]),
+    );
+  }
+}
+
+export class V3Position {
+  constructor(
+    public readonly positionManager: string,
+    public readonly tokenId: bigint,
+    public readonly token0: string,
+    public readonly token1: string,
+    public readonly fee: number,
+    public readonly tickLower: number,
+    public readonly tickUpper: number,
+    public readonly liquidity: bigint,
+    public readonly tokensOwed0: bigint,
+    public readonly tokensOwed1: bigint,
+    public readonly locked: boolean,
+    public readonly unlockTime: bigint,
+  ) {}
+
+  static fromRaw(r: Raw): V3Position {
+    return new V3Position(
+      String(r[0]), BigInt(r[1]), String(r[2]), String(r[3]), Number(r[4]), Number(r[5]),
+      Number(r[6]), BigInt(r[7]), BigInt(r[8]), BigInt(r[9]), Boolean(r[10]), BigInt(r[11]),
+    );
+  }
+}
+
+export class V4Position {
+  constructor(
+    public readonly positionManager: string,
+    public readonly tokenId: bigint,
+    public readonly poolId: string,
+    public readonly currency0: string,
+    public readonly currency1: string,
+    public readonly fee: number,
+    public readonly tickSpacing: number,
+    public readonly hooks: string,
+    public readonly tickLower: number,
+    public readonly tickUpper: number,
+    public readonly liquidity: bigint,
+    public readonly locked: boolean,
+    public readonly unlockTime: bigint,
+  ) {}
+
+  static fromRaw(r: Raw): V4Position {
+    return new V4Position(
+      String(r[0]), BigInt(r[1]), String(r[2]), String(r[3]), String(r[4]), Number(r[5]),
+      Number(r[6]), String(r[7]), Number(r[8]), Number(r[9]), BigInt(r[10]), Boolean(r[11]), BigInt(r[12]),
+    );
+  }
+}
+
+export class V2PoolState {
+  constructor(
+    public readonly pair: string,
+    public readonly token0: string,
+    public readonly token1: string,
+    public readonly reserve0: bigint,
+    public readonly reserve1: bigint,
+  ) {}
+
+  static fromRaw(r: Raw): V2PoolState {
+    return new V2PoolState(String(r[0]), String(r[1]), String(r[2]), BigInt(r[3]), BigInt(r[4]));
+  }
+}
+
+export class V3PoolState {
+  constructor(
+    public readonly pool: string,
+    public readonly token0: string,
+    public readonly token1: string,
+    public readonly fee: number,
+    public readonly tick: number,
+    public readonly sqrtPriceX96: bigint,
+    public readonly liquidity: bigint,
+    public readonly tickSpacing: number,
+  ) {}
+
+  static fromRaw(r: Raw): V3PoolState {
+    return new V3PoolState(
+      String(r[0]), String(r[1]), String(r[2]), Number(r[3]), Number(r[4]), BigInt(r[5]),
+      BigInt(r[6]), Number(r[7]),
+    );
+  }
+}
+
+export class V4PoolState {
+  constructor(
+    public readonly poolId: string,
+    public readonly currency0: string,
+    public readonly currency1: string,
+    public readonly fee: number,
+    public readonly tickSpacing: number,
+    public readonly hooks: string,
+    public readonly sqrtPriceX96: bigint,
+    public readonly tick: number,
+    public readonly protocolFee: number,
+    public readonly lpFee: number,
+    public readonly liquidity: bigint,
+  ) {}
+
+  static fromRaw(r: Raw): V4PoolState {
+    return new V4PoolState(
+      String(r[0]), String(r[1]), String(r[2]), Number(r[3]), Number(r[4]), String(r[5]),
+      BigInt(r[6]), Number(r[7]), Number(r[8]), Number(r[9]), BigInt(r[10]),
+    );
+  }
+}
+
+/** A time-lock entry from `getLocks`. */
+export class Lock {
+  constructor(
+    public readonly kind: number,
+    public readonly asset: string,
+    public readonly tokenIdOrAmount: bigint,
+    public readonly lockTime: bigint,
+    public readonly unlockTime: bigint,
+    public readonly owner: string,
+    public readonly tokenA: string,
+    public readonly tokenB: string,
+    public readonly nonce: bigint,
+  ) {}
+
+  static fromRaw(r: Raw): Lock {
+    return new Lock(
+      Number(r[0]), String(r[1]), BigInt(r[2]), BigInt(r[3]), BigInt(r[4]), String(r[5]),
+      String(r[6]), String(r[7]), BigInt(r[8]),
+    );
+  }
+
+  get kindName(): string {
+    const name = LockKind[this.kind];
+    return name !== undefined ? name : `UNKNOWN(${this.kind})`;
+  }
+}
+
+/** Uncollected fees of a V3/V4 position from `getClaimableFees`. */
+export class ClaimableFees {
+  constructor(
+    public readonly token0: string,
+    public readonly amount0: bigint,
+    public readonly token1: string,
+    public readonly amount1: bigint,
+  ) {}
+
+  static fromRaw(r: Raw): ClaimableFees {
+    return new ClaimableFees(String(r[0]), BigInt(r[1]), String(r[2]), BigInt(r[3]));
+  }
+}
+
+/** Paged referral-fee balances from `getReferralFeeTokens`. */
+export class ReferralFeeTokens {
+  constructor(
+    public readonly tokens: string[],
+    public readonly amounts: bigint[],
+    public readonly maxIndex: number,
+  ) {}
+
+  static fromRaw(r: Raw): ReferralFeeTokens {
+    return new ReferralFeeTokens(
+      [...r[0]].map((a) => String(a)),
+      [...r[1]].map((x) => BigInt(x)),
+      Number(r[2]),
+    );
+  }
+
+  asDict(): Record<string, bigint> {
+    const out: Record<string, bigint> = {};
+    for (let i = 0; i < this.tokens.length && i < this.amounts.length; i++) {
+      out[this.tokens[i]] = this.amounts[i];
+    }
+    return out;
+  }
+}

package/src/util.ts

@@ -0,0 +1,20 @@
+/**
+ * Small numeric helpers that match Python semantics exactly, so this SDK is a
+ * faithful 1:1 port (and not subtly off by a unit at .5 boundaries).
+ */
+
+/**
+ * Round half-to-even ("banker's rounding"), matching Python's built-in `round()`.
+ *
+ * JS `Math.round` rounds half **up** (0.5 -> 1, 2.5 -> 3), while Python rounds
+ * half to the nearest **even** integer (0.5 -> 0, 2.5 -> 2). The SDK's tax-bps
+ * and price-impact-bps math goes through Python `round()`, so we reproduce it.
+ */
+export function pyRound(x: number): number {
+  const floor = Math.floor(x);
+  const diff = x - floor;
+  if (diff < 0.5) return floor;
+  if (diff > 0.5) return floor + 1;
+  // Exactly .5 -> pick the even neighbour.
+  return floor % 2 === 0 ? floor : floor + 1;
+}