Developer
Integrating programmatically.
The TypeScript SDK — @logswap/sdk — wraps the ManagerC / ManagerF /
RouterC / RouterF / LensC / LensF surface. It is offline-first: market and position addressing need no
RPC and no deployment.
| module | what it does |
|---|---|
keys | PoolKey and poolId = keccak256(abi.encode(key)) — market identity |
ids | the ERC-6909 id namespace: position-class ids, token-claim ids, floor/cap packing |
client | the handle, plus assertVersion — refuse a deployment the ABI was not built for |
pools | market discovery from Initialize logs, pool state, lpEdge |
positions | classes, balances, claimable fees, the bit-255 position/claim split |
swap | exact-in / exact-out, multi-hop, and exact quotes via the revert-quoter |
liquidity | mint, blended mint, zap, update, move, harvest, burn |
claims | fee claims and the 6909 operator grant |
onboard | the three approvals — ERC-20 → Permit2 → router — and the 6909 grant |
fpool | the F-pool surface: seed, swap, zap, harvest, derived reads |
indexer | log replay into a read model |
The SDK hides the contract split
Which contract hosts which action is currently decided by EIP-170 headroom, not by design. So
callers address markets by PoolKey and never choose a contract, and a future re-homing of a function
is an SDK patch rather than a breaking change.
Two derivations you must get right
Both are computed offline, and both are frozen for the life of a deployment — a change to either is a migration, not an upgrade.
poolId = keccak256(abi.encode(key))
positionId = (1 << 255) | (keccak256(poolId ‖ packed) >> 1)
poolId is the primary key of the entire read model. If a client's derivation disagrees with the
contract's, it addresses the wrong pool or the wrong position — silently, with funds behind it.
So the SDK checks against vectors generated by the contract, not by hand: 45 vectors covering
poolId, positionId and the pack/unpack round-trip, verified non-vacuous by mutation (shifting the
id derivation by one bit fails all 45). A diff in the vectors file during an ordinary change means
something is wrong, by definition.
Market identity and permissions
Use the complete key for the deployment you target. The current C-pool key includes fixed
swapFee, mintFee and policy fields. A zero swapFee means fee-free, subject to admission policy.
Older dynamic-fee key layouts are incompatible. Check contract and SDK versions before encoding a key.
Split every ERC-6909 Transfer on bit 255. Clear means a token claim, not a position. An indexer
that ignores this reports phantom LP positions for market makers parking inventory.
Check the token spender. A Permit2 deployment needs an ERC-20 allowance to Permit2 and a Permit2 allowance to the router. A deployment without Permit2 needs a direct allowance to the router. See Getting started.
Quoting
Quotes run the real swap path and revert with the result, so they are exact — including the pending per-block variance fold — and need no funded balances.
lens.previewSwapExactIn(key, baseIn, amountIn)
lens.previewSwapExactOut(key, baseOut, amountOut)
lens.previewBlend(key, targetFloor, L) // the two-rung split for an arbitrary floorBatching
The manager-wide lock is the integration primitive. Call unlock(data) first and every operation
inside accrues signed transient deltas that settle once, at close — so blending two ladder rungs,
funding a mint from a swap, or routing three hops each cost one transfer per token. Intermediate
tokens never move.
A positive delta may instead be taken as a token claim, an ERC-6909 IOU on tokens left inside the manager. One parked balance serves every market in that singleton.
Reading pool health
Everything an integrator needs is derived, not stored:
F fee income per unit of active L (swap fees + mint fees)
Σ realized quadratic variation
F − Σ/2 the model-free LP edge — no oracle, no volatility model, no benchmark
logFloor derived log-floor; see the mathematical mapping below
is the cumulative fee return on active liquidity over the measurement window. For an active uncapped position, divide by its starting to express that return on starting capital. An APR additionally requires annualizing by the window duration.
logFloor maps to for one base and for a multi-asset pool.
compositeX maps to and reduces to for one base.
See Notation.
The pipeline
logswap (forge) ──► contracts/abi/*.json ──► wagmi codegen ──► src/generated.ts
▲ │
contracts.ref (pinned SHA) the SDK wrappers
Nothing is hand-copied. contracts.ref pins the SHA, npm run codegen clones and regenerates, and
tsc is the drift gate — so a contract change that breaks the SDK is a red build rather than a
runtime surprise.