@logswap/sdk 0.5.35

package/dist/ids.d.ts

@@ -0,0 +1,42 @@
+/**
+ * ids.ts — the ERC-6909 id namespace, computed OFFLINE.
+ *
+ * Two kinds of id share one ERC-6909 space, split on **bit 255**:
+ *
+ *   bit 255 SET    a position class:  (1 << 255) | (keccak256(poolId ‖ packed) >> 1)
+ *   bit 255 CLEAR  a token claim:     uint160(tokenAddress)
+ *
+ * Both are **tier-1 frozen** (docs/app.md). The namespace bit is what lets a wallet UI, a lender, or
+ * an indexer tell an LP position from a bearer IOU — and an indexer that ignores it will report
+ * phantom LP positions for market makers parking inventory.
+ */
+import { type Address, type Hex } from "viem";
+/** Sentinel meaning "no cap" — `type(int256).min`. */
+export declare const NO_CAP: bigint;
+/**
+ * `packed` — the class's (floor, cap) as two 32-bit fields: `kFloor + 2^31` in the low half,
+ * `kCap + 2^31` in the high half, or zero there when uncapped.
+ *
+ * Throws on an off-grid floor or cap rather than producing an id the manager would reject, so a
+ * client fails at the call site instead of at the transaction.
+ */
+export declare function packFloorCap(tickSpacing: bigint, floor: bigint, cap?: bigint): bigint;
+/** Inverse of {@link packFloorCap}. `capped === false` means the cap field is unset. */
+export declare function unpackFloorCap(tickSpacing: bigint, packed: bigint): {
+    floor: bigint;
+    cap: bigint;
+    capped: boolean;
+};
+/**
+ * The position-class id: `(1 << 255) | (keccak256(poolId ‖ packed) >> 1)`.
+ *
+ * The `>> 1` is what frees bit 255 for the namespace flag, so the hash contributes 255 bits.
+ * `abi.encodePacked(bytes32, uint64)` is 40 bytes — 32 for the pool id, 8 for `packed`.
+ */
+export declare function positionId(poolId_: Hex, tickSpacing: bigint, floor: bigint, cap?: bigint): bigint;
+/** A token claim's id is just the token address. */
+export declare function claimId(token: Address): bigint;
+/** True for a position class, false for a token claim. Split every 6909 `Transfer` on this. */
+export declare function isPosition(id: bigint): boolean;
+/** The token an id refers to, or `null` if the id is a position rather than a claim. */
+export declare function claimToken(id: bigint): Address | null;

package/dist/ids.js

@@ -0,0 +1,72 @@
+/**
+ * ids.ts — the ERC-6909 id namespace, computed OFFLINE.
+ *
+ * Two kinds of id share one ERC-6909 space, split on **bit 255**:
+ *
+ *   bit 255 SET    a position class:  (1 << 255) | (keccak256(poolId ‖ packed) >> 1)
+ *   bit 255 CLEAR  a token claim:     uint160(tokenAddress)
+ *
+ * Both are **tier-1 frozen** (docs/app.md). The namespace bit is what lets a wallet UI, a lender, or
+ * an indexer tell an LP position from a bearer IOU — and an indexer that ignores it will report
+ * phantom LP positions for market makers parking inventory.
+ */
+import { concatHex, keccak256, pad, toHex } from "viem";
+/** Packing offset for the signed tick index `k`, so it fits an unsigned 32-bit field. */
+const ID_OFFSET = 1n << 31n;
+/** Sentinel meaning "no cap" — `type(int256).min`. */
+export const NO_CAP = -(2n ** 255n);
+const BIT_255 = 1n << 255n;
+/**
+ * `packed` — the class's (floor, cap) as two 32-bit fields: `kFloor + 2^31` in the low half,
+ * `kCap + 2^31` in the high half, or zero there when uncapped.
+ *
+ * Throws on an off-grid floor or cap rather than producing an id the manager would reject, so a
+ * client fails at the call site instead of at the transaction.
+ */
+export function packFloorCap(tickSpacing, floor, cap = NO_CAP) {
+    if (tickSpacing <= 0n)
+        throw new Error("tickSpacing must be positive");
+    if (floor % tickSpacing !== 0n)
+        throw new Error(`floor ${floor} is off-grid for spacing ${tickSpacing}`);
+    let packed = BigInt.asUintN(64, floor / tickSpacing + ID_OFFSET);
+    if (cap !== NO_CAP) {
+        if (cap <= floor)
+            throw new Error("cap must be strictly above floor");
+        if (cap % tickSpacing !== 0n)
+            throw new Error(`cap ${cap} is off-grid for spacing ${tickSpacing}`);
+        packed |= BigInt.asUintN(64, cap / tickSpacing + ID_OFFSET) << 32n;
+    }
+    return packed;
+}
+/** Inverse of {@link packFloorCap}. `capped === false` means the cap field is unset. */
+export function unpackFloorCap(tickSpacing, packed) {
+    const kf = (packed & 0xffffffffn) - ID_OFFSET;
+    const hi = packed >> 32n;
+    const capped = hi !== 0n;
+    return { floor: kf * tickSpacing, cap: capped ? (hi - ID_OFFSET) * tickSpacing : NO_CAP, capped };
+}
+/**
+ * The position-class id: `(1 << 255) | (keccak256(poolId ‖ packed) >> 1)`.
+ *
+ * The `>> 1` is what frees bit 255 for the namespace flag, so the hash contributes 255 bits.
+ * `abi.encodePacked(bytes32, uint64)` is 40 bytes — 32 for the pool id, 8 for `packed`.
+ */
+export function positionId(poolId_, tickSpacing, floor, cap = NO_CAP) {
+    const packed = packFloorCap(tickSpacing, floor, cap);
+    const h = BigInt(keccak256(concatHex([poolId_, pad(toHex(packed), { size: 8 })])));
+    return BIT_255 | (h >> 1n);
+}
+/** A token claim's id is just the token address. */
+export function claimId(token) {
+    return BigInt(token);
+}
+/** True for a position class, false for a token claim. Split every 6909 `Transfer` on this. */
+export function isPosition(id) {
+    return (id & BIT_255) !== 0n;
+}
+/** The token an id refers to, or `null` if the id is a position rather than a claim. */
+export function claimToken(id) {
+    if (isPosition(id))
+        return null;
+    return pad(toHex(id), { size: 20 });
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Logswap SDK — typed, offline-first helpers over the CPoolManager / Router / Lens surface.
+ *
+ * The manager/router/lens split is an EIP-170 artifact, not a design boundary, so it is hidden
+ * here: callers address markets by `PoolKey` and never choose a contract. A future re-homing of
+ * a function is then an SDK patch rather than a breaking change (docs/app.md, tier 2).
+ */
+export * from "./keys.js";
+export * from "./ids.js";
+export * from "./client.js";
+export * from "./pools.js";
+export * from "./positions.js";
+export * from "./write.js";
+export * from "./swap.js";
+export * from "./liquidity.js";
+export * from "./actions.js";
+export * from "./claims.js";
+export * from "./onboard.js";
+export * from "./indexer.js";
+export * from "./tokencache.js";
+export * from "./fpool.js";
+export { cPoolManagerAbi, fPoolManagerAbi, logswapLensAbi, logswapRouterAbi } from "./generated.js";
+export * from "./admin.js";

package/dist/index.js

@@ -0,0 +1,23 @@
+/**
+ * Logswap SDK — typed, offline-first helpers over the CPoolManager / Router / Lens surface.
+ *
+ * The manager/router/lens split is an EIP-170 artifact, not a design boundary, so it is hidden
+ * here: callers address markets by `PoolKey` and never choose a contract. A future re-homing of
+ * a function is then an SDK patch rather than a breaking change (docs/app.md, tier 2).
+ */
+export * from "./keys.js";
+export * from "./ids.js";
+export * from "./client.js";
+export * from "./pools.js";
+export * from "./positions.js";
+export * from "./write.js";
+export * from "./swap.js";
+export * from "./liquidity.js";
+export * from "./actions.js";
+export * from "./claims.js";
+export * from "./onboard.js";
+export * from "./indexer.js";
+export * from "./tokencache.js";
+export * from "./fpool.js";
+export { cPoolManagerAbi, fPoolManagerAbi, logswapLensAbi, logswapRouterAbi } from "./generated.js";
+export * from "./admin.js";

package/dist/indexer.d.ts

@@ -0,0 +1,91 @@
+/**
+ * indexer.ts — reads the rindexer GraphQL that state cannot answer.
+ *
+ * The division of labour matters and is not arbitrary: **the indexer enumerates, the chain
+ * values.** ERC-6909 has no enumeration, so there is no way to ask a node "which positions exist in
+ * this pool" — only the `IdRegistered` log knows. But an indexed row is a historical fact, and `L`
+ * changes with every mint, burn and harvest afterwards. So ids come from here and the current `L`
+ * is read on-chain, rather than trusting a number that was true at index time.
+ */
+import type { Hex } from "viem";
+import type { LogswapClient } from "./client.js";
+import { type DiscoveredMarket } from "./pools.js";
+import { type PoolKey } from "./keys.js";
+export interface IndexerError {
+    message: string;
+}
+/**
+ * A `bytea` column renders as `0x…` but FILTERS as `\x…`.
+ *
+ * Passing back the exact value the API just gave you returns zero rows, with no error — the query
+ * is valid, the comparison simply never matches. Every filter on a hash goes through here.
+ *
+ * The result is passed as a **variable**, never interpolated into query text: `\x` is not a legal
+ * escape inside a GraphQL string literal, so an interpolated filter fails with
+ * `Syntax Error: Invalid character escape sequence`. Variables carry the value untouched.
+ */
+export declare function bytea(hex: Hex): string;
+export declare function gql<T>(url: string, query: string, variables?: Record<string, unknown>, signal?: AbortSignal): Promise<T>;
+/** A position class as the chain registered it: the floor/cap geometry, fixed for the id's life. */
+export interface RegisteredId {
+    id: bigint;
+    floor: bigint;
+    cap: bigint;
+    capped: boolean;
+}
+/** Every position class ever registered in a pool. Historical — some may since have burnt to zero. */
+export declare function registeredIds(url: string, poolId: Hex, signal?: AbortSignal): Promise<RegisteredId[]>;
+export interface PoolPosition extends RegisteredId {
+    /** Total exposure across every holder, read from the chain — not from the indexed row. */
+    L: bigint;
+    shares: bigint;
+    /** Spot is inside this position's range, so it is earning fees. */
+    active: boolean;
+}
+/**
+ * Every live position class in a pool, split by whether it is earning.
+ *
+ * A position is **active** when spot sits at or above its floor and, if capped, below its cap —
+ * the same condition the tick ladder applies when it steps `lActive`.
+ *
+ * Classes that have burnt to `L = 0` are dropped: they are registered forever, but a list of
+ * positions should show positions, not the history of ones that existed.
+ */
+export declare function poolPositions(c: LogswapClient, url: string, poolId: Hex, x: bigint, signal?: AbortSignal): Promise<PoolPosition[]>;
+/** Is the indexer answering? Used to degrade a screen rather than fail it. */
+export declare function indexerHealthy(url: string, signal?: AbortSignal): Promise<boolean>;
+/**
+ * Markets, from the indexer rather than a log scan.
+ *
+ * `discoverMarkets` reads `Initialize` logs straight from the node, which is correct until the node
+ * stops keeping them. anvil's `--prune-history` drops historical transactions and receipts beyond a
+ * window, so on a devnet that mines steadily the deployment's own logs age out and a scan from
+ * block 0 returns nothing — while the contracts remain perfectly alive. Any real chain has the same
+ * shape in a different form: archive-depth `getLogs` is exactly what public RPCs refuse.
+ *
+ * An indexer does not have that problem, because it recorded the event when it happened. This is
+ * the more durable path and should be preferred wherever an indexer is configured, with the log
+ * scan as the fallback for when it is not.
+ *
+ * `Initialize` carries every field of the `PoolKey`, so the key is rebuilt exactly and `poolId` is
+ * recomputed locally rather than trusted from the row — the same offline derivation the SDK uses
+ * everywhere else, so a wrong id fails loudly instead of addressing the wrong pool.
+ */
+export declare function discoverMarketsIndexed(url: string, signal?: AbortSignal): Promise<DiscoveredMarket[]>;
+/**
+ * Markets, preferring the indexer and falling back to a log scan.
+ *
+ * The order matters: the indexer is authoritative for history, the node is authoritative for state.
+ * A market the node can no longer tell you about is still a market.
+ */
+export declare function discoverMarketsBest(c: LogswapClient, url: string | undefined, signal?: AbortSignal): Promise<{
+    markets: DiscoveredMarket[];
+    source: "indexer" | "chain";
+}>;
+/**
+ * The UNCAPPED position classes of a pool, from the CHAIN alone: the lens enumerates live floors
+ * (one bitmap bit each), and an uncapped id is a pure function of (key, floor). No indexer.
+ * Capped classes need `IdRegistered` replay and are absent here — callers that also want those
+ * use the indexed `poolPositions` and fall back to this when the indexer is missing or stale.
+ */
+export declare function poolPositionsFromChain(c: LogswapClient, key: PoolKey, x: bigint): Promise<PoolPosition[]>;

package/dist/indexer.js

@@ -0,0 +1,197 @@
+/**
+ * indexer.ts — reads the rindexer GraphQL that state cannot answer.
+ *
+ * The division of labour matters and is not arbitrary: **the indexer enumerates, the chain
+ * values.** ERC-6909 has no enumeration, so there is no way to ask a node "which positions exist in
+ * this pool" — only the `IdRegistered` log knows. But an indexed row is a historical fact, and `L`
+ * changes with every mint, burn and harvest afterwards. So ids come from here and the current `L`
+ * is read on-chain, rather than trusting a number that was true at index time.
+ */
+import { cPoolManagerAbi } from "./generated.js";
+import { getPositionClass } from "./positions.js";
+import { discoverMarkets } from "./pools.js";
+import { poolId } from "./keys.js";
+import { NO_CAP } from "./ids.js";
+/**
+ * A `bytea` column renders as `0x…` but FILTERS as `\x…`.
+ *
+ * Passing back the exact value the API just gave you returns zero rows, with no error — the query
+ * is valid, the comparison simply never matches. Every filter on a hash goes through here.
+ *
+ * The result is passed as a **variable**, never interpolated into query text: `\x` is not a legal
+ * escape inside a GraphQL string literal, so an interpolated filter fails with
+ * `Syntax Error: Invalid character escape sequence`. Variables carry the value untouched.
+ */
+export function bytea(hex) {
+    return `\\x${hex.replace(/^0x/, "")}`;
+}
+export async function gql(url, query, variables, signal) {
+    const res = await fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ query, variables }),
+        signal,
+    });
+    if (!res.ok)
+        throw new Error(`indexer: HTTP ${res.status} from ${url}`);
+    const body = (await res.json());
+    if (body.errors?.length)
+        throw new Error(`indexer: ${body.errors.map((e) => e.message).join("; ")}`);
+    if (!body.data)
+        throw new Error("indexer: empty response");
+    return body.data;
+}
+/** Every position class ever registered in a pool. Historical — some may since have burnt to zero. */
+export async function registeredIds(url, poolId, signal) {
+    const q = `query Ids($pool: String!) {
+    allIdRegistereds(condition: {poolId: $pool}, first: 1000) { nodes { id floor cap capped } }
+  }`;
+    const d = await gql(url, q, { pool: bytea(poolId) }, signal);
+    return d.allIdRegistereds.nodes.map((n) => ({
+        id: BigInt(n.id),
+        floor: BigInt(n.floor),
+        cap: BigInt(n.cap),
+        capped: n.capped,
+    }));
+}
+/**
+ * Every live position class in a pool, split by whether it is earning.
+ *
+ * A position is **active** when spot sits at or above its floor and, if capped, below its cap —
+ * the same condition the tick ladder applies when it steps `lActive`.
+ *
+ * Classes that have burnt to `L = 0` are dropped: they are registered forever, but a list of
+ * positions should show positions, not the history of ones that existed.
+ */
+export async function poolPositions(c, url, poolId, x, signal) {
+    const ids = await registeredIds(url, poolId, signal);
+    const rows = await Promise.all(ids.map(async (r) => {
+        const cls = await getPositionClass(c, r.id);
+        return { ...r, L: cls.L, shares: cls.shares, active: x >= r.floor && (!r.capped || x < r.cap) };
+    }));
+    return rows.filter((r) => r.L > 0n).sort((a, b) => (b.L > a.L ? 1 : b.L < a.L ? -1 : 0));
+}
+/** Is the indexer answering? Used to degrade a screen rather than fail it. */
+export async function indexerHealthy(url, signal) {
+    try {
+        await gql(url, "{ __typename }", undefined, signal);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Markets, from the indexer rather than a log scan.
+ *
+ * `discoverMarkets` reads `Initialize` logs straight from the node, which is correct until the node
+ * stops keeping them. anvil's `--prune-history` drops historical transactions and receipts beyond a
+ * window, so on a devnet that mines steadily the deployment's own logs age out and a scan from
+ * block 0 returns nothing — while the contracts remain perfectly alive. Any real chain has the same
+ * shape in a different form: archive-depth `getLogs` is exactly what public RPCs refuse.
+ *
+ * An indexer does not have that problem, because it recorded the event when it happened. This is
+ * the more durable path and should be preferred wherever an indexer is configured, with the log
+ * scan as the fallback for when it is not.
+ *
+ * `Initialize` carries every field of the `PoolKey`, so the key is rebuilt exactly and `poolId` is
+ * recomputed locally rather than trusted from the row — the same offline derivation the SDK uses
+ * everywhere else, so a wrong id fails loudly instead of addressing the wrong pool.
+ */
+export async function discoverMarketsIndexed(url, signal) {
+    const q = `{ allInitializes(first: 1000) { nodes {
+    poolId base quote tickSpacing phiMin kappa alpha x0 blockNumber txHash
+  } } }`;
+    const d = await gql(url, q, undefined, signal);
+    return d.allInitializes.nodes.map((n) => {
+        const key = {
+            base: n.base,
+            quote: n.quote,
+            tickSpacing: BigInt(n.tickSpacing),
+            phiMin: BigInt(n.phiMin),
+            kappa: BigInt(n.kappa),
+            alpha: BigInt(n.alpha),
+        };
+        return {
+            key,
+            poolId: poolId(key),
+            x0: BigInt(n.x0),
+            blockNumber: BigInt(n.blockNumber),
+            transactionHash: n.txHash,
+        };
+    });
+}
+/**
+ * Markets, preferring the indexer and falling back to a log scan.
+ *
+ * The order matters: the indexer is authoritative for history, the node is authoritative for state.
+ * A market the node can no longer tell you about is still a market.
+ */
+export async function discoverMarketsBest(c, url, signal) {
+    if (url) {
+        try {
+            const markets = await discoverMarketsIndexed(url, signal);
+            // The indexer is a CACHE and the chain is the truth. After a redeploy the indexer keeps
+            // serving the previous deployment's markets; calling the new manager with those keys makes
+            // every read revert, refresh-proof (it presented as "phiEff reverted", forever). So verify
+            // each candidate against the manager the client is actually pointed at, and keep only the
+            // markets that exist there; if none survive, the chain scan is the answer.
+            if (markets.length) {
+                const alive = (await Promise.all(markets.map(async (m) => {
+                    try {
+                        await c.public.readContract({
+                            address: c.addresses.cPoolManager,
+                            abi: cPoolManagerAbi,
+                            functionName: "phiEff",
+                            args: [m.key],
+                        });
+                        return m;
+                    }
+                    catch {
+                        return null;
+                    }
+                }))).filter((m) => m !== null);
+                if (alive.length)
+                    return { markets: alive, source: "indexer" };
+            }
+        }
+        catch {
+            /* fall through — a missing indexer must not cost you the market list */
+        }
+    }
+    return { markets: await discoverMarkets(c), source: "chain" };
+}
+/**
+ * The UNCAPPED position classes of a pool, from the CHAIN alone: the lens enumerates live floors
+ * (one bitmap bit each), and an uncapped id is a pure function of (key, floor). No indexer.
+ * Capped classes need `IdRegistered` replay and are absent here — callers that also want those
+ * use the indexed `poolPositions` and fall back to this when the indexer is missing or stale.
+ */
+export async function poolPositionsFromChain(c, key, x) {
+    const { logswapLensAbi } = await import("./generated.js");
+    const floors = (await c.public.readContract({
+        address: c.addresses.lens,
+        abi: logswapLensAbi,
+        functionName: "liveTicks",
+        args: [key],
+    }));
+    const pool = poolId(key);
+    const rows = await Promise.all([...floors].map(async (floor) => {
+        const id = (await c.public.readContract({
+            address: c.addresses.cPoolManager,
+            abi: cPoolManagerAbi,
+            functionName: "idOf",
+            args: [key, floor],
+        }));
+        const [L, shares] = (await c.public.readContract({
+            address: c.addresses.cPoolManager,
+            abi: cPoolManagerAbi,
+            functionName: "positions",
+            args: [id],
+        }));
+        if (L === 0n)
+            return null;
+        return { id, poolId: pool, floor, cap: NO_CAP, capped: false, L, shares, active: x >= floor };
+    }));
+    return rows.filter((r) => r !== null);
+}

package/dist/keys.d.ts

@@ -0,0 +1,40 @@
+/**
+ * keys.ts — market identity, computed OFFLINE.
+ *
+ * A market is a `PoolKey`, and its id is the hash of that key. Both are **tier-1 frozen**
+ * (docs/app.md): the key is in every keyed signature *and* `poolId = keccak256(abi.encode(key))`,
+ * so adding a field would change every selector and re-identify every market, orphaning all
+ * indexed history.
+ *
+ * This module reimplements `PoolKeyLib.toId` in TypeScript so a client can address a market with no
+ * RPC at all. `test/derivation.test.ts` pins it against vectors generated by the contract itself —
+ * if the two ever disagree, that test fails rather than the SDK silently addressing the wrong pool.
+ */
+import { type Address, type Hex } from "viem";
+/**
+ * The economic tuple that IS the market. Field order is load-bearing: it is the ABI encoding order,
+ * so it must match `src/types/PoolKey.sol` exactly.
+ */
+export interface PoolKey {
+    base: Address;
+    quote: Address;
+    /** Log-tick spacing, WAD. The LP-boundary ladder — position floors and caps. */
+    tickSpacing: bigint;
+    /** Fee floor, WAD. `0n` selects `DEFAULT_FEE_MIN` (2 bp) at read time. */
+    phiMin: bigint;
+    /** Variance-fee coefficient, WAD. `0n` disables the dynamic fee. */
+    kappa: bigint;
+    /** EMA decay, WAD. `0n` selects `DEFAULT_ALPHA` (1/2) at read time. */
+    alpha: bigint;
+}
+/**
+ * `poolId = keccak256(abi.encode(key))` — the primary key of the entire read model.
+ *
+ * Note the zero-vs-default caveat the Solidity type documents: `phiMin` and `alpha` of `0` resolve
+ * to their defaults at READ time, so a key carrying `0n` and one carrying the resolved default are
+ * DIFFERENT markets with different ids, even though they behave identically. Always address a
+ * market by the key it was initialized with.
+ */
+export declare function poolId(key: PoolKey): Hex;
+/** Structural equality of two keys — i.e. "the same market". */
+export declare function sameMarket(a: PoolKey, b: PoolKey): boolean;

package/dist/keys.js

@@ -0,0 +1,50 @@
+/**
+ * keys.ts — market identity, computed OFFLINE.
+ *
+ * A market is a `PoolKey`, and its id is the hash of that key. Both are **tier-1 frozen**
+ * (docs/app.md): the key is in every keyed signature *and* `poolId = keccak256(abi.encode(key))`,
+ * so adding a field would change every selector and re-identify every market, orphaning all
+ * indexed history.
+ *
+ * This module reimplements `PoolKeyLib.toId` in TypeScript so a client can address a market with no
+ * RPC at all. `test/derivation.test.ts` pins it against vectors generated by the contract itself —
+ * if the two ever disagree, that test fails rather than the SDK silently addressing the wrong pool.
+ */
+import { encodeAbiParameters, keccak256 } from "viem";
+const POOL_KEY_ABI = [
+    {
+        type: "tuple",
+        components: [
+            { name: "base", type: "address" },
+            { name: "quote", type: "address" },
+            { name: "tickSpacing", type: "int256" },
+            { name: "phiMin", type: "uint256" },
+            { name: "kappa", type: "uint256" },
+            { name: "alpha", type: "uint256" },
+        ],
+    },
+];
+/**
+ * `poolId = keccak256(abi.encode(key))` — the primary key of the entire read model.
+ *
+ * Note the zero-vs-default caveat the Solidity type documents: `phiMin` and `alpha` of `0` resolve
+ * to their defaults at READ time, so a key carrying `0n` and one carrying the resolved default are
+ * DIFFERENT markets with different ids, even though they behave identically. Always address a
+ * market by the key it was initialized with.
+ */
+export function poolId(key) {
+    return keccak256(encodeAbiParameters(POOL_KEY_ABI, [
+        {
+            base: key.base,
+            quote: key.quote,
+            tickSpacing: key.tickSpacing,
+            phiMin: key.phiMin,
+            kappa: key.kappa,
+            alpha: key.alpha,
+        },
+    ]));
+}
+/** Structural equality of two keys — i.e. "the same market". */
+export function sameMarket(a, b) {
+    return poolId(a) === poolId(b);
+}