@logswap/sdk 0.5.35

package/dist/onboard.js

@@ -0,0 +1,188 @@
+/**
+ * onboard.ts — getting a wallet to the point where router writes actually work.
+ *
+ * There are **three separate approvals** with three separate failure modes, and a UI that surfaces
+ * them late produces failed transactions instead of prompts:
+ *
+ *   1. ERC-20 → Permit2      once per token, forever. Only when the router is Permit2-wired.
+ *   2. Permit2 → router      a standing allowance, by transaction or by signature.
+ *   3. 6909 operator grant   once per wallet, covers every market. Needed by burn/update/move.
+ *
+ * **The trap this module exists for:** when the router is deployed with Permit2, approving the
+ * ERC-20 to the *router* is not enough and not used — the pull goes through Permit2, and the
+ * failure is `NotAllowed()` from Permit2 rather than anything naming an allowance. Approving the
+ * router directly looks correct and does nothing.
+ */
+import { parseAbi, zeroAddress } from "viem";
+import { requireWallet } from "./write.js";
+export const MAX_UINT256 = (1n << 256n) - 1n;
+export const MAX_UINT160 = (1n << 160n) - 1n;
+export const MAX_UINT48 = (1n << 48n) - 1n;
+const ERC20 = parseAbi([
+    "function approve(address spender, uint256 amount) returns (bool)",
+    "function allowance(address owner, address spender) view returns (uint256)",
+]);
+const PERMIT2 = parseAbi([
+    "function approve(address token, address spender, uint160 amount, uint48 expiration)",
+    "function allowance(address owner, address token, address spender) view returns (uint160 amount, uint48 expiration, uint48 nonce)",
+    "function transferFrom(address from, address to, uint160 amount, address token)",
+]);
+/** Is this deployment's router wired to Permit2? Decides which approval path applies. */
+export function usesPermit2(c) {
+    return !!c.addresses.permit2 && c.addresses.permit2 !== zeroAddress;
+}
+/** The contract that will actually pull tokens: Permit2 when wired, otherwise the router. */
+export function spenderFor(c) {
+    return usesPermit2(c) ? c.addresses.permit2 : c.addresses.router;
+}
+/** Step 1 — approve the *puller* on an ERC-20. Once per token. */
+export async function approveToken(c, token, amount = MAX_UINT256) {
+    const { account } = requireWallet(c);
+    return c.wallet.writeContract({
+        address: token,
+        abi: ERC20,
+        functionName: "approve",
+        args: [spenderFor(c), amount],
+        account,
+        chain: c.wallet.chain,
+    });
+}
+/**
+ * Step 2 — the standing Permit2 allowance for the router.
+ *
+ * No-op when the deployment has no Permit2. Prefer the signature flow (`applyPermit2` on the
+ * router, bundled through `multicall`) in production; this transaction form is what a test or a
+ * simple UI wants.
+ */
+export async function approvePermit2ForRouter(c, token, amount = MAX_UINT160, expiration = MAX_UINT48) {
+    if (!usesPermit2(c))
+        return null;
+    const { account } = requireWallet(c);
+    return c.wallet.writeContract({
+        address: c.addresses.permit2,
+        abi: PERMIT2,
+        functionName: "approve",
+        args: [token, c.addresses.router, amount, Number(expiration)],
+        account,
+        chain: c.wallet.chain,
+    });
+}
+/**
+ * Both token-side steps in order, skipping any already satisfied.
+ *
+ * Returns the hashes actually sent, so a UI can report "2 approvals" honestly rather than always
+ * prompting twice.
+ */
+export async function onboardToken(c, token, need) {
+    // The address, not the account object: these two are READS. Signing paths take the object.
+    const { address } = requireWallet(c);
+    const sent = [];
+    const allowance = (await c.public.readContract({
+        address: token,
+        abi: ERC20,
+        functionName: "allowance",
+        args: [address, spenderFor(c)],
+    }));
+    if (allowance < need) {
+        const h = await approveToken(c, token);
+        await c.public.waitForTransactionReceipt({ hash: h });
+        sent.push(h);
+    }
+    if (usesPermit2(c)) {
+        const [amt] = (await c.public.readContract({
+            address: c.addresses.permit2,
+            abi: PERMIT2,
+            functionName: "allowance",
+            args: [address, token, c.addresses.router],
+        }));
+        if (amt < need) {
+            const h = await approvePermit2ForRouter(c, token);
+            if (h) {
+                await c.public.waitForTransactionReceipt({ hash: h });
+                sent.push(h);
+            }
+        }
+    }
+    return sent;
+}
+export async function checkTokenReadiness(c, token, owner, need) {
+    const allowance = (await c.public.readContract({
+        address: token,
+        abi: ERC20,
+        functionName: "allowance",
+        args: [owner, spenderFor(c)],
+    }));
+    let needsPermit2Approval = false;
+    if (usesPermit2(c)) {
+        const [amt] = (await c.public.readContract({
+            address: c.addresses.permit2,
+            abi: PERMIT2,
+            functionName: "allowance",
+            args: [owner, token, c.addresses.router],
+        }));
+        needsPermit2Approval = amt < need;
+    }
+    return { usesPermit2: usesPermit2(c), needsTokenApproval: allowance < need, needsPermit2Approval };
+}
+// ─── the signature path: allowances that ride inside the action's own transaction ─────────────
+//
+// The rationalized flow. A token's ONLY unavoidable transaction is its one-time ERC-20 approval
+// to Permit2; the Permit2→router allowance is set by an EIP-712 SIGNATURE (free, instant, no
+// gas) submitted as an `applyPermit2` call INSIDE the same multicall as the action. Minting on a
+// fresh token is then one transaction, not three — the pattern the router's `applyPermit2` +
+// `multicall` were built for, and the one canonical Permit2 UX uses.
+const PERMIT2_TYPES = {
+    PermitDetails: [
+        { name: "token", type: "address" },
+        { name: "amount", type: "uint160" },
+        { name: "expiration", type: "uint48" },
+        { name: "nonce", type: "uint48" },
+    ],
+    PermitSingle: [
+        { name: "details", type: "PermitDetails" },
+        { name: "spender", type: "address" },
+        { name: "sigDeadline", type: "uint256" },
+    ],
+};
+/**
+ * For each token whose Permit2→router allowance is missing: read the nonce, have the wallet SIGN
+ * a PermitSingle (a signature prompt, not a transaction), and return the encoded `applyPermit2`
+ * calls ready to ride in a router multicall. Tokens already allowed produce nothing.
+ */
+export async function permit2SigCalls(c, tokens) {
+    if (!usesPermit2(c))
+        return [];
+    const { account, address: owner } = requireWallet(c);
+    const chainId = await c.public.getChainId();
+    const calls = [];
+    for (const token of [...new Set(tokens.map((t) => t.toLowerCase()))]) {
+        const [amt, , nonce] = (await c.public.readContract({
+            address: c.addresses.permit2,
+            abi: PERMIT2,
+            functionName: "allowance",
+            args: [owner, token, c.addresses.router],
+        }));
+        if (amt >= 1n << 120n)
+            continue; // effectively infinite already
+        const message = {
+            details: { token, amount: MAX_UINT160, expiration: Number(MAX_UINT48), nonce },
+            spender: c.addresses.router,
+            sigDeadline: BigInt(Math.floor(Date.now() / 1000)) + 1800n,
+        };
+        const signature = await c.wallet.signTypedData({
+            account,
+            domain: { name: "Permit2", chainId, verifyingContract: c.addresses.permit2 },
+            types: PERMIT2_TYPES,
+            primaryType: "PermitSingle",
+            message,
+        });
+        const { encodeFunctionData } = await import("viem");
+        const { logswapRouterAbi } = await import("./generated.js");
+        calls.push(encodeFunctionData({
+            abi: logswapRouterAbi,
+            functionName: "applyPermit2",
+            args: [owner, message, signature],
+        }));
+    }
+    return calls;
+}

package/dist/pools.d.ts

@@ -0,0 +1,182 @@
+/**
+ * pools.ts — market state and discovery.
+ *
+ * Two things worth knowing before reading further.
+ *
+ * **Markets are discovered from logs, not configuration.** `Initialize` carries the ENTIRE
+ * `PoolKey` in the clear, so a client can reconstruct any market's key — and therefore call any
+ * keyed function — having never been told the market exists. There is no registry to maintain.
+ *
+ * **`x` is the state, price is derived.** The contract stores $x = \log p$ and materialises the
+ * price only where unavoidable; `priceOf` below mirrors that, and is lossy in the way any float
+ * conversion is. Prefer comparing in log space when precision matters.
+ */
+import { type Address, type Hex } from "viem";
+import type { LogswapClient } from "./client.js";
+import { type PoolKey } from "./keys.js";
+/** The manager's `getPool` view, decoded. Field-for-field with `PoolView` in the contract. */
+export interface PoolState {
+    initialized: boolean;
+    backstopSeeded: boolean;
+    /** $x = \log p$, WAD — the stored state. */
+    x: bigint;
+    /** Exposure currently earning. Steps only when a floor or cap is crossed. */
+    lActive: bigint;
+    reserveBase: bigint;
+    reserveQuote: bigint;
+    /** Fee-per-unit-L accumulator: $\phi \cdot \mathrm{TV}(\log p)$. */
+    F: bigint;
+    /** Quadratic variation of log-price, $\Sigma = \int (dx)^2$. */
+    bigSigma: bigint;
+    sigma2Ema: bigint;
+    currentK: bigint;
+    protocolOwed: bigint;
+    minBackstopL: bigint;
+    backstopFloor: bigint;
+}
+/** Read a market's full state by key. */
+export declare function getPool(c: LogswapClient, key: PoolKey): Promise<PoolState>;
+/** The effective fee right now: $\max(\phi_{\min}, \kappa\sqrt{\sigma^2_{\text{ema}}})$, capped. */
+export declare function phiEff(c: LogswapClient, key: PoolKey): Promise<bigint>;
+/**
+ * Price from the stored log-price. **Lossy** — `x` is exact and this is a float, so use it for
+ * display and never for arithmetic you intend to send back on-chain.
+ */
+export declare function priceOf(state: Pick<PoolState, "x">, scale?: number): number;
+/**
+ * The factor between the chain's price and the human one. The chain's log-price is of the WEI
+ * ratio, so with a 6-dec USDC quote and an 18-dec base the human price is `e^x · 10^12`. Pass
+ * this as `scale` to {@link priceOf}, {@link floorPrice} and `fPoolPriceOf` — with 18/18 tokens
+ * it is 1 and nothing changes.
+ */
+export declare function priceScale(baseDecimals: number, quoteDecimals: number): number;
+/**
+ * The model-free LP edge, $F - \tfrac12\Sigma$ — the protocol's headline metric, in quote per unit
+ * of exposure.
+ *
+ * $F$ is fee income per unit active $L$; $\Sigma$ is the realised quadratic variation, whose half
+ * is the LVR a log pool pays. The difference is what an LP actually earns, with no model of the
+ * price process assumed. Both ride on every `Swap` event, so this is reconstructible from logs
+ * alone (docs/app.md) — no state read needed if you are already indexing.
+ *
+ * Signed: negative means variation has outrun fee income over the pool's life.
+ */
+export declare function lpEdge(state: Pick<PoolState, "F" | "bigSigma">): bigint;
+/** A market discovered from an `Initialize` log — the full key, plus where it was created. */
+export interface DiscoveredMarket {
+    key: PoolKey;
+    poolId: Hex;
+    /** The market's opening log-price. */
+    x0: bigint;
+    blockNumber: bigint;
+    transactionHash: Hex;
+}
+/**
+ * Enumerate markets from `Initialize` logs.
+ *
+ * This is the whole market registry: the event carries every key field rather than just the id,
+ * deliberately, so nothing downstream needs a configured list. Pass `fromBlock` as the manager's
+ * deployment block — scanning from genesis is slow and pointless.
+ */
+export declare function discoverMarkets(c: LogswapClient, opts?: {
+    fromBlock?: bigint;
+    toBlock?: bigint;
+    base?: Address;
+    quote?: Address;
+}): Promise<DiscoveredMarket[]>;
+/**
+ * Ladder shape: the live FLOORS, in log-price WAD — **not** tick indices.
+ *
+ * Named `liveFloors` deliberately. The lens function it wraps is called `liveTicks`, which reads as
+ * if it returns `k`; it returns `k * tickSpacing`. Multiplying by the spacing again yields an
+ * off-grid value and an `OffGrid` revert at the next call, which is a confusing place to discover
+ * the mistake.
+ */
+export declare function liveFloors(c: LogswapClient, key: PoolKey): Promise<readonly bigint[]>;
+/** Is this floor on the market's grid, and inside `MAX_ABS_FLOOR`? Pure — no RPC on the manager. */
+export declare function isValidFloor(c: LogswapClient, key: PoolKey, floor: bigint): Promise<boolean>;
+/**
+ * A market's token decimals, read from the tokens themselves.
+ *
+ * **Never assume these.** A market's two tokens routinely differ (USDC 6 against WETH 18), the
+ * manager itself probes `decimals()` to scale `minBackstopL`, and a token that does not implement
+ * it falls back to 18. Hardcoding a guess makes every parse and every display wrong by orders of
+ * magnitude while the contract behaves perfectly — which reads as "the app is broken".
+ */
+export declare function marketDecimals(c: LogswapClient, key: PoolKey): Promise<{
+    base: number;
+    quote: number;
+}>;
+/** A token as a UI needs it: address, symbol and decimals, all read from the chain. */
+export interface TokenInfo {
+    address: Address;
+    symbol: string;
+    decimals: number;
+}
+/**
+ * Both sides of a market, for labelling and scaling.
+ *
+ * **Decimals are read from the token and never guessed.** They used to fall back to 18 on any
+ * failure, which quietly reintroduced the worst bug this stack has had: an 18 assumed for a
+ * 6-decimal token is a 10^12 error in a number that goes on to `parseUnits` and becomes a transfer
+ * amount. A wrong scale is indistinguishable from a working app until somebody moves funds, so a
+ * read that will not resolve must fail loudly instead.
+ *
+ * `symbol` keeps a fallback because it is a label: a market shown as `0x5FbD…` is ugly, not wrong.
+ *
+ * Retries first, because a blip on the transport is not the same as a token that has no `decimals`,
+ * and killing a market over one dropped packet is its own kind of wrong.
+ *
+ * **Cached** per (chain, address) — see `tokencache.ts` for why only successes are stored and why
+ * the chain id is part of the key. Concurrent calls for the same token share one read, which
+ * matters because the quote asset is usually the same across every market in a deployment.
+ */
+export declare function marketTokens(c: LogswapClient, key: PoolKey): Promise<{
+    base: TokenInfo;
+    quote: TokenInfo;
+}>;
+/** Format a quote-denominated amount for display, given the quote's decimals. */
+export declare function formatQuote(amount: bigint, quoteDecimals: number): string;
+/** Fees the pool has accrued over its life, in QUOTE units: $F \cdot L$. */
+export declare function feesQuote(state: Pick<PoolState, "F" | "lActive">): bigint;
+/** The LP edge in QUOTE units: $(F - \tfrac12\Sigma) \cdot L$. Signed. */
+export declare function edgeQuote(state: Pick<PoolState, "F" | "bigSigma" | "lActive">): bigint;
+/** The pool floor as a price. **Lossy** — display only, like {@link priceOf}. */
+export declare function floorPrice(state: Pick<PoolState, "backstopFloor">, scale?: number): number;
+/** $\log(p / p_{\text{floor}}) = x - \xi$ — how far spot sits above the floor, in log units (WAD). */
+export declare function floorDistance(state: Pick<PoolState, "x" | "backstopFloor">): bigint;
+/**
+ * $-\log(p/p_{\text{floor}})$ as a fraction: the log-drawdown from spot down to the floor.
+ *
+ * **Negative** while price is above the floor — it is how far price has to fall, so a UI can print
+ * it with its sign and mean it. Zero at the floor.
+ *
+ * This is the LOG measure, not the arithmetic one: the actual price drawdown is
+ * $e^{-\Delta} - 1$, which differs materially once the distance is large (a log distance of 0.7
+ * is a 50% price fall, not 70%).
+ */
+export declare function floorDrawdown(state: Pick<PoolState, "x" | "backstopFloor">): number;
+/** The arithmetic price drawdown to the floor, $p_{\text{floor}}/p - 1$. Negative above the floor. */
+export declare function floorDrawdownPrice(state: Pick<PoolState, "x" | "backstopFloor">): number;
+/**
+ * Annualise a per-unit-L WAD rate over the window it accrued in.
+ *
+ * `F` is cumulative fee income per unit of exposure since the pool opened, so dividing by the
+ * elapsed time and scaling to a year gives a rate directly — no price process assumed. Returns a
+ * fraction: 0.12 is 12%.
+ *
+ * Treat it as what it is: a *realised* rate over one short devnet window, not a forecast.
+ */
+export declare function annualise(perUnitL: bigint, elapsedSeconds: bigint): number;
+/** When a market was created, as a unix timestamp — the denominator for {@link annualise}. */
+export declare function marketOpenedAt(c: LogswapClient, m: DiscoveredMarket): Promise<bigint>;
+/**
+ * Create a C market: `initialize(key, x0)` on the manager — a call, not a deployment. Manager-
+ * direct by design: creation moves no funds, so the router adds nothing. The pool id is
+ * `poolId(key)` (pure) and the market is tradeable immediately; the first mint funds it.
+ */
+export declare function initializeMarket(c: LogswapClient, a: {
+    key: PoolKey;
+    x0: bigint;
+    account: Address;
+}): Promise<`0x${string}`>;