@logswap/sdk 0.5.35

package/src/swap.ts

@@ -0,0 +1,140 @@
+/**
+ * swap.ts — trading.
+ *
+ * All four shapes go through the router, which is where slippage and deadline live. The manager's
+ * merged `swap(key, baseSide, amount, limit)` uses a NEGATIVE amount for exact-out; that convention
+ * is deliberately not exposed here — callers say `swapExactOut`.
+ */
+
+import type { Address, Hash } from "viem";
+import { logswapLensAbi, logswapRouterAbi } from "./generated.js";
+import type { LogswapClient } from "./client.js";
+import type { PoolKey } from "./keys.js";
+import { resolveDeadline, resolveRecipient, sendRouterWrite, type WriteOptions , sendRouterWriteWithPermits } from "./write.js";
+
+/**
+ * Quote an exact-in swap. Exact, not approximate — the lens is a revert-quoter that runs the real
+ * swap and reverts with the result, so what it returns is what execution returns, bit for bit
+ * (including the dynamic fee, even across a block boundary with the variance fold pending).
+ *
+ * `simulate`, not a plain read: the function is non-view by construction.
+ */
+export async function quoteExactIn(
+  c: LogswapClient,
+  key: PoolKey,
+  baseIn: boolean,
+  amountIn: bigint,
+): Promise<bigint> {
+  const { result } = await c.public.simulateContract({
+    address: c.addresses.lens,
+    abi: logswapLensAbi,
+    functionName: "previewSwapExactIn",
+    args: [key, baseIn, amountIn],
+  });
+  return result as bigint;
+}
+
+/** Quote an exact-out swap: how much input it will cost. Exact, same mechanism as above. */
+export async function quoteExactOut(
+  c: LogswapClient,
+  key: PoolKey,
+  baseOut: boolean,
+  amountOut: bigint,
+): Promise<bigint> {
+  const { result } = await c.public.simulateContract({
+    address: c.addresses.lens,
+    abi: logswapLensAbi,
+    functionName: "previewSwapExactOut",
+    args: [key, baseOut, amountOut],
+  });
+  return result as bigint;
+}
+
+export interface SwapExactInArgs extends WriteOptions {
+  key: PoolKey;
+  /** true = base in, quote out (price falls). false = quote in, base out (price rises). */
+  baseIn: boolean;
+  amountIn: bigint;
+  /** Reverts below this. Derive from a quote with `withSlippage(q, bps, "output")`. */
+  minOut: bigint;
+}
+
+export async function swapExactIn(c: LogswapClient, a: SwapExactInArgs): Promise<Hash> {
+  return sendRouterWriteWithPermits(c, {
+    abi: logswapRouterAbi,
+    functionName: "swapExactIn",
+    args: [a.key, a.baseIn, a.amountIn, a.minOut, resolveRecipient(c, a), resolveDeadline(a)],
+  }, [a.baseIn ? a.key.base : a.key.quote]);
+}
+
+export interface SwapExactOutArgs extends WriteOptions {
+  key: PoolKey;
+  /** true = base out (price rises). false = quote out (price falls). */
+  baseOut: boolean;
+  amountOut: bigint;
+  /** Reverts above this. Derive from a quote with `withSlippage(q, bps, "input")`. */
+  maxIn: bigint;
+}
+
+export async function swapExactOut(c: LogswapClient, a: SwapExactOutArgs): Promise<Hash> {
+  return sendRouterWriteWithPermits(c, {
+    abi: logswapRouterAbi,
+    functionName: "swapExactOut",
+    args: [a.key, a.baseOut, a.amountOut, a.maxIn, resolveRecipient(c, a), resolveDeadline(a)],
+  }, [a.baseOut ? a.key.quote : a.key.base]);
+}
+
+/** One leg of a route. `baseIn` is that hop's direction through its own market. */
+export interface Hop {
+  key: PoolKey;
+  baseIn: boolean;
+}
+
+export interface SwapPathArgs extends WriteOptions {
+  hops: readonly Hop[];
+  amountIn: bigint;
+  minOut: bigint;
+}
+
+/**
+ * Multi-hop, all inside ONE lock.
+ *
+ * The singleton dividend: deltas accrue per TOKEN across the whole route, so an intermediate asset
+ * is never actually moved — a three-market route transfers only the tokens at the endpoints. The
+ * path is not validated on-chain, and it does not need to be: a mis-chained hop leaves a dangling
+ * delta and the lock refuses to close.
+ */
+export async function swapExactInPath(c: LogswapClient, a: SwapPathArgs): Promise<Hash> {
+  if (a.hops.length === 0) throw new Error("logswap: empty path");
+  return sendRouterWrite(c, {
+    abi: logswapRouterAbi,
+    functionName: "swapExactInPath",
+    args: [
+      a.hops.map((h) => ({ key: h.key, baseIn: h.baseIn })),
+      a.amountIn,
+      a.minOut,
+      resolveRecipient(c, a),
+      resolveDeadline(a),
+    ],
+  });
+}
+
+/**
+ * Which token a hop takes in and pays out — the check a UI should run before building a route, so
+ * a mis-chained path fails in the form rather than at the lock.
+ */
+export function hopTokens(h: Hop): { tokenIn: Address; tokenOut: Address } {
+  return h.baseIn
+    ? { tokenIn: h.key.base, tokenOut: h.key.quote }
+    : { tokenIn: h.key.quote, tokenOut: h.key.base };
+}
+
+/** True when every hop's output feeds the next hop's input. */
+export function isPathChained(hops: readonly Hop[]): boolean {
+  for (let i = 1; i < hops.length; i++) {
+    const prev = hopTokens(hops[i - 1]!);
+    const next = hopTokens(hops[i]!);
+    if (prev.tokenOut.toLowerCase() !== next.tokenIn.toLowerCase()) return false;
+  }
+  return true;
+}

package/src/tokencache.ts

@@ -0,0 +1,169 @@
+/**
+ * tokencache.ts — remember token metadata so it is read once, not once per screen.
+ *
+ * `marketTokens` costs four reads per market and every screen calls it. On two markets that is
+ * free; on fifty it is a hundred round trips on every navigation, over a tunnel.
+ *
+ * **A cache over a value that becomes a transaction amount is a way to be wrong, so three rules
+ * hold here and are enforced by tests:**
+ *
+ * 1. **Only successes are stored.** The previous fix made a failed `decimals()` read throw rather
+ *    than assume 18; caching a failure would reintroduce that bug with a longer half-life.
+ * 2. **The key includes the chain id.** The same address is a different token on a different
+ *    chain — a mock USDC at 18 decimals on a devnet, the real one at 6 on mainnet. Keying on
+ *    address alone is the classic version of this bug and it survives a page reload.
+ * 3. **A fallback symbol is never stored.** `symbol` degrades to `0x5FbD…` on failure, which is
+ *    fine as a label but must not be persisted — one blip would name the token that forever.
+ *
+ * 4. **A resettable chain never reaches the persistent store.** Rule 3's premise is that decimals
+ *    are immutable *for the life of a token*, and the key's premise is that an address names one
+ *    token forever. Both hold on a public chain. Neither holds on a local one: restart anvil and
+ *    the very same deterministic addresses come back holding DIFFERENT contracts. That is not
+ *    hypothetical — a `logswap.token.31337:0x5fbd…` entry saying USDC has 18 decimals outlived the
+ *    deploy that wrote it and made every quote-denominated number in the app read as zero, with
+ *    nothing anywhere reporting a fault. Those chains get the memory store, so a page reload is
+ *    enough to correct them.
+ *
+ * Decimals are immutable for the life of a token: ERC-20 exposes no way to change them, and a token
+ * that did would break every integration, not just this one. That is what makes an unbounded TTL
+ * correct rather than merely convenient — on a chain whose addresses are permanent.
+ */
+
+import type { Address } from "viem";
+
+export interface CachedToken {
+  symbol: string;
+  decimals: number;
+}
+
+/** Somewhere to keep entries. Sync and tiny on purpose — `localStorage` fits, and so does a Map. */
+export interface TokenStore {
+  get(key: string): string | null;
+  set(key: string, value: string): void;
+  /** Drop everything this store owns. Optional: a store that cannot enumerate may omit it. */
+  clear?(): void;
+}
+
+const memory = new Map<string, string>();
+
+/** The default: per-process, no persistence. Works in node, workers and a browser alike. */
+export const memoryStore: TokenStore = {
+  get: (k) => memory.get(k) ?? null,
+  set: (k, v) => void memory.set(k, v),
+  clear: () => memory.clear(),
+};
+
+/**
+ * `localStorage`, when there is one. Returns the memory store otherwise, so a caller never has to
+ * branch on the environment — and a browser in private mode degrades instead of throwing.
+ */
+export function browserStore(prefix = "logswap.token."): TokenStore {
+  try {
+    if (typeof localStorage === "undefined") return memoryStore;
+    localStorage.getItem(`${prefix}probe`); // Safari private mode throws on access, not on use
+    return {
+      get: (k) => {
+        try {
+          return localStorage.getItem(prefix + k);
+        } catch {
+          return null;
+        }
+      },
+      set: (k, v) => {
+        try {
+          localStorage.setItem(prefix + k, v);
+        } catch {
+          /* quota or private mode — the cache is an optimisation, never a requirement */
+        }
+      },
+      // Only this prefix, never the whole of localStorage: the app's own keys live there too.
+      clear: () => {
+        try {
+          for (const k of Object.keys(localStorage)) if (k.startsWith(prefix)) localStorage.removeItem(k);
+        } catch {
+          /* nothing to do — see set */
+        }
+      },
+    };
+  } catch {
+    return memoryStore;
+  }
+}
+
+let store: TokenStore = memoryStore;
+
+/** Swap the backing store. Call once at startup; `browserStore()` is the usual argument. */
+export function setTokenStore(s: TokenStore): void {
+  store = s;
+}
+
+/** Address casing varies by source, so normalise — otherwise the same token gets two entries. */
+const keyOf = (chainId: number, address: Address) => `${chainId}:${address.toLowerCase()}`;
+
+/**
+ * Chains whose addresses are not permanent identities: a development node can be wiped and
+ * redeployed, and because deployment addresses are derived from a deterministic nonce sequence the
+ * SAME address comes back holding a different contract. 1337 is ganache's and hardhat's legacy id,
+ * 31337 anvil's and hardhat's default, 31338 and 31339 the unimod and logswap devnets — both
+ * persisted with `--state`, both documented as resettable by deleting that file.
+ *
+ * Add to this set rather than removing from it: a chain wrongly listed here costs some RPC round
+ * trips, while one wrongly absent silently serves a stale scale, which is the bug this exists for.
+ */
+export const RESETTABLE_CHAINS: ReadonlySet<number> = new Set([1337, 31337, 31338, 31339]);
+
+/** True when a `(chainId, address)` pair cannot be trusted to name one contract forever. */
+export function isResettableChain(chainId: number): boolean {
+  return RESETTABLE_CHAINS.has(chainId);
+}
+
+/**
+ * The store an entry for this chain may use. A resettable chain gets memory — good enough to stop
+ * one navigation re-reading the same token fifty times, and gone on reload, which is exactly the
+ * lifetime over which its addresses can be trusted.
+ */
+const storeFor = (chainId: number): TokenStore => (isResettableChain(chainId) ? memoryStore : store);
+
+export function readCachedToken(chainId: number, address: Address): CachedToken | null {
+  const raw = storeFor(chainId).get(keyOf(chainId, address));
+  if (!raw) return null;
+  try {
+    const v = JSON.parse(raw) as CachedToken;
+    // Validate on the way OUT as well as in: the store is shared with other tabs and other builds,
+    // and a corrupt entry must be ignored rather than trusted.
+    if (typeof v?.decimals !== "number" || !Number.isInteger(v.decimals) || v.decimals < 0 || v.decimals > 36) {
+      return null;
+    }
+    if (typeof v.symbol !== "string" || v.symbol === "") return null;
+    return v;
+  } catch {
+    return null;
+  }
+}
+
+export function writeCachedToken(chainId: number, address: Address, t: CachedToken): void {
+  storeFor(chainId).set(keyOf(chainId, address), JSON.stringify({ symbol: t.symbol, decimals: t.decimals }));
+}
+
+/**
+ * Forget everything, including reads still in flight.
+ *
+ * For tests, and for a devnet that redeployed its mocks to the same addresses — the one case where
+ * a token at a known address legitimately changes its decimals, because it is a different contract
+ * wearing the same address.
+ */
+export function clearTokenCache(): void {
+  memory.clear();
+  // The persistent store too. It did not used to be, which made this function useless against the
+  // one situation its own doc names: the entry that survives a redeploy lives in `localStorage`,
+  // so clearing only memory left it in place and the next read served it straight back.
+  store.clear?.();
+  onClear.forEach((f) => f());
+}
+
+const onClear = new Set<() => void>();
+
+/** Internal: lets `pools.ts` drop its in-flight map when the cache is cleared. */
+export function registerCacheClear(f: () => void): void {
+  onClear.add(f);
+}

package/src/write.ts

@@ -0,0 +1,134 @@
+/**
+ * write.ts — shared plumbing for every mutating call.
+ *
+ * Two conventions every write helper inherits, so no caller has to remember them:
+ *
+ * **Deadlines are mandatory on-chain and defaulted here.** Every mutating router entry carries
+ * `checkDeadline`. Passing `type(uint256).max` disables it, which is what most SDKs do implicitly
+ * and is a real hazard for a user whose transaction sits in the mempool through a price move. The
+ * default is a bounded window; pass `deadline: NEVER` only deliberately.
+ *
+ * **Slippage is expressed as a bound, never as a percentage of a stale quote.** Helpers take the
+ * raw `minOut`/`maxIn` the contract wants. `withSlippage()` derives one from a quote when that is
+ * what you have — but the bound is what ships.
+ */
+
+import type { Address, Hash } from "viem";
+import type { LogswapClient } from "./client.js";
+
+/** Disables the deadline check. Deliberate opt-out, never a default. */
+export const NEVER = (1n << 256n) - 1n;
+
+/** Default deadline window: 20 minutes, the same order as every major DEX front end. */
+export const DEFAULT_DEADLINE_SECONDS = 20n * 60n;
+
+export interface WriteOptions {
+  /** Absolute unix seconds. Defaults to now + {@link DEFAULT_DEADLINE_SECONDS}. */
+  deadline?: bigint;
+  /** Who receives the output. Defaults to the wallet account. */
+  recipient?: Address;
+}
+
+export function resolveDeadline(o: WriteOptions | undefined, now = Date.now()): bigint {
+  return o?.deadline ?? BigInt(Math.floor(now / 1000)) + DEFAULT_DEADLINE_SECONDS;
+}
+
+/**
+ * The wallet's account, as the ACCOUNT OBJECT rather than its address.
+ *
+ * This distinction decides how the transaction is signed, and getting it wrong fails in only half
+ * the cases — which is how it survived a long time here. viem treats a bare `0x…` address as a
+ * *JSON-RPC account* and calls `eth_sendTransaction`, asking the NODE to sign. That is right for an
+ * injected wallet and wrong for a local account, which must sign in-process and send
+ * `eth_sendRawTransaction`.
+ *
+ * A dev node holds the keys for its own accounts, so passing an address appears to work right up
+ * until someone uses a key the node does not have — a bot, a script, CI, or a real user's wallet.
+ * Passing the object lets viem pick the correct path for both kinds.
+ */
+export function requireWallet(c: LogswapClient): { account: NonNullable<LogswapClient["wallet"]>["account"]; address: Address } {
+  const account = c.wallet?.account;
+  if (!c.wallet || !account) {
+    throw new Error("logswap: this call needs a wallet client — createLogswapClient({ wallet, … })");
+  }
+  return { account, address: account.address };
+}
+
+export function resolveRecipient(c: LogswapClient, o?: WriteOptions): Address {
+  return o?.recipient ?? requireWallet(c).address;
+}
+
+/**
+ * Turn a quoted amount into a slippage bound.
+ *
+ * `bps` is basis points of tolerance. Direction matters: an output bound floors, an input bound
+ * ceilings. Getting that backwards produces a bound that can never bind, which is worse than no
+ * bound at all because it looks protective.
+ */
+export function withSlippage(quoted: bigint, bps: number, side: "output" | "input"): bigint {
+  if (bps < 0 || bps > 10_000) throw new Error(`logswap: slippage bps out of range: ${bps}`);
+  const b = BigInt(Math.round(bps));
+  return side === "output" ? (quoted * (10_000n - b)) / 10_000n : (quoted * (10_000n + b)) / 10_000n;
+}
+
+/**
+ * Send a router write with a gas buffer over an explicit estimate.
+ *
+ * A swap's gas is path-dependent: how many ticks it crosses depends on the price when it LANDS, not
+ * when it was estimated, and the variance kernel does more work when a block boundary has passed
+ * since the last touch. An exact `eth_estimateGas` can therefore OutOfGas one block later. Every
+ * write goes through here.
+ */
+export async function sendRouterWrite(
+  c: LogswapClient,
+  args: { abi: readonly unknown[]; functionName: string; args: readonly unknown[]; bufferPct?: bigint },
+): Promise<Hash> {
+  const { account } = requireWallet(c);
+  const params = {
+    address: c.addresses.router,
+    abi: args.abi,
+    functionName: args.functionName,
+    args: args.args,
+    account,
+    chain: c.wallet!.chain,
+  } as never;
+
+  const estimate = await c.public.estimateContractGas(params);
+  const gas = (estimate * (100n + (args.bufferPct ?? 30n))) / 100n;
+  return c.wallet!.writeContract({ ...(params as object), gas } as never);
+}
+
+/** Simulate a router write and return its decoded result, without sending. */
+export async function simulateRouterWrite<T>(
+  c: LogswapClient,
+  args: { abi: readonly unknown[]; functionName: string; args: readonly unknown[]; account?: Address },
+): Promise<T> {
+  const account = args.account ?? c.wallet?.account?.address;
+  const { result } = await c.public.simulateContract({
+    address: c.addresses.router,
+    abi: args.abi,
+    functionName: args.functionName,
+    args: args.args,
+    account,
+  } as never);
+  return result as T;
+}
+
+/**
+ * A router write that carries its own Permit2 permissions: missing allowances for `pullTokens`
+ * are SIGNED (no gas, no extra transaction) and submitted as `applyPermit2` calls in one
+ * multicall with the action. The 3-transaction mint becomes 1. Falls through to a plain write
+ * when nothing is missing or Permit2 is not wired.
+ */
+export async function sendRouterWriteWithPermits(
+  c: LogswapClient,
+  args: { abi: readonly unknown[]; functionName: string; args: readonly unknown[]; bufferPct?: bigint },
+  pullTokens: Address[],
+): Promise<Hash> {
+  const { permit2SigCalls } = await import("./onboard.js");
+  const sigCalls = await permit2SigCalls(c, pullTokens).catch(() => []);
+  if (sigCalls.length === 0) return sendRouterWrite(c, args);
+  const { encodeFunctionData } = await import("viem");
+  const inner = encodeFunctionData({ abi: args.abi, functionName: args.functionName, args: args.args } as never);
+  return sendRouterWrite(c, { abi: args.abi, functionName: "multicall", args: [[...sigCalls, inner]], bufferPct: args.bufferPct });
+}