LpClient reference

Every LpClient method — args, returns, read/write, the on-chain function it calls, and its degradation envelope — for buying in-range IL protection (claim A).

LpClient is the LP-facing surface of @inflexion/sdk: it prices, buys, inspects, and settles in-range IL protection on a specific Uniswap v3 position. It is the surface that carries Claim A — LPs are always paid min(realized_IL, MaxIL) from the underwriter’s collateral, with no bad debt in FULL mode — and the only one that holds a signer for LP writes.

Access it as sdk.lp from the one-call factory. It is the only surface wired with engineBaseUrl / telemetryUrl / fetchImpl, because it is the only one that talks to the Path-B quote engine and emits the latent-demand telemetry ping.

LPs are always paid with no bad debt in FULL mode — qualified: capped payoff + solvent USDC + oracle/settlement liveness.

The no-bad-debt guarantee is exact only under the full clause:

• FULL collateralization — the underwriter has posted exactly MaxIL per swap, locked for the life of the position.
• Capped payoff — the payout is min(realized_IL, MaxIL). The cap is load-bearing: it is what makes payout ≤ collateral hold by construction.
• Solvent USDC — the collateral numeraire (dUSDC) holds its peg and remains redeemable.
• Oracle / settlement liveness — the price oracle stays live and settle() runs within the protocol’s settlement window.
• No rehypothecation breach — locked collateral stays instantly liquid; it is never routed to utilization-gated venues.

Stated without these qualifiers, the guarantee is not correct.

The read contract: graceful degradation

Every read that needs the live spot price P0 wraps the OracleManager.getPrice call. If that oracle is stale or the L2 sequencer is reported down, the manager reverts, and the SDK catches it and returns a typed NotPriceable envelope rather than throwing:

type Priceable<T> =
  | ({ priceable: true } & T)
  | { priceable: false; reason: DegradeReason; detail?: string }

So the calling pattern is always a discriminated-union check, never a try/catch:

const preview = await lp.previewPremium(tokenId, marketId)
if (!preview.priceable) {
  // reason ∈ 'oracle-degraded' | 'market-unknown' | 'position-unknown' | …
  showDegraded(preview.reason)
} else {
  showPremium(preview.best, preview.path)
}

LP writes are the one place a missing signer is a hard error: with no walletClient, buyProtection / settle / poke throw a clear error on call (not at construction), so a read-only SDK still constructs and prices fine. See the full envelope taxonomy in SDK degradation.

Method reference

Decimals are load-bearing. dUSDC is the 6-decimal numéraire — every maxPremium, premium, V0, and maxIL is a 6-dec raw bigint (1 dUSDC = 1_000_000n). dWETH is 18-dec, Chainlink feeds are 8-dec, and ratios (aWad, bWad, σ_ref, loads) are WAD = 1e18. See decimals & units.

Method	R/W	Returns	Calls (on-chain)	Degradation
getLoadParams	R	LoadParams (cached)	Core loadParams	throws on no-RPC (cached after 1st)
resolveGeometry	R	Priceable<{ geometry }>	NPM positions, Core markets / oracleDerivedSqrtPriceX96, TickMath, OracleManager getPrice, ILMath computeMaxIL / getAmountsForLiquidity	market-unknown / position-unknown / oracle-degraded
listEligiblePositions	R	EligiblePosition[]	NPM balanceOf / tokenOfOwnerByIndex / positions, then resolveGeometry	[] on no-NPM; per-row inRange:undefined if oracle degraded
previewPremium	R (+opt poke W)	Priceable<PreviewResult>	FVO fairPremium, ConvexityVault inventory, Core loadParams / markets; engine GET /quote; opt VolOracle.poke	NotPriceable if oracle degraded; Path B silently absent if engine unreachable
getPayoffCurve	R	Priceable<PayoffCurve>	ILMath computeIL over a sqrt-price grid	NotPriceable if oracle degraded
buyProtection	W	Hex (txHash)	NPM approve, dUSDC allowance / approve, Core createSwapRouted / createSwapPathA / createSwap	throws clear error if no wallet
getProtectionStatus	R	ProtectionStatus | {available:false, reason}	Core swaps + settlePreview (via simulateContract), OracleManager getPrice, Core oracleDerivedSqrtPriceX96	available:false on unknown swap; ilToDate is itself Priceable
getClaimableFees	R	ClaimableFees | {available:false}	Core swaps, NPM positions (checkpointed tokensOwed0/1)	under-states; precise needs subgraph
settle	W	Hex (txHash)	Core swaps (recover expiry), Chainlink round-walk, Core settle(swapId, hintRoundId)	throws clear error if no wallet
autoProtect	W (unless dryRun)	AutoProtectResult[]	orchestrates list → preview → buy; scans swaps / nextSwapId for ACTIVE dedupe	per-row skipped / error; never throws
poke	W	Hex (txHash)	VolOracle.poke(token)	throws if no wallet
findHintRoundId	R	bigint	Chainlink latestRoundData / getRoundData backwards walk	returns best round on un-fetchable phase boundary

---

getLoadParams

Reads and caches the protocol’s load-stack parameters from InflexionCore.loadParams. These feed the client-side TS-port load math (regime bands, util/disp curves, maxLoadBps = invariant I10).

(no args)

None.

returns · LoadParams

The on-chain load parameters. Cached after the first read; throws only if there is no RPC client and the cache is empty.

const params = await lp.getLoadParams()
// params.maxLoadBps is the I10 ceiling every MM quote and pool load is clamped to.

---

resolveGeometry

Resolves a position NFT + a market into the full settlement geometry — the heart of pricing. It reads the NFT’s ticks, derives sqrtPaX96 / sqrtPbX96 from TickMath, reads the live sqrtP0X96 (from the oracle-derived price), converts to the WAD ratios a/b, computes entry amounts and MaxIL, and stamps the inRange gate.

tokenId · bigint · required

The Uniswap v3 position NFT id.

marketId · 0x${string} · required

The bytes32 market id (token0/token1/fee/duration). See markets.

returns · Priceable<{ geometry: LpGeometry }>

On success, { priceable: true, geometry }. On failure, { priceable: false, reason } with reason ∈ 'market-unknown' | 'position-unknown' | 'oracle-degraded'.

Show LpGeometry

tokenId · bigint

token0 / token1 · 0x${string}

fee · number

tickLower / tickUpper · number

liquidity · bigint

The position liquidity L — stamped here and stored at creation, never re-read from the NFT at settlement (invariant I6).

sqrtPaX96 / sqrtPbX96 / sqrtP0X96 · bigint

Range bounds and live spot, in Uniswap Q64.96 sqrt-price form.

aWad / bWad · bigint

a = (sqrtPa/sqrtP0)², b = (sqrtPb/sqrtP0)² in WAD — the geometry the Φ-sum and load stack consume.

amount0Entry / amount1Entry · bigint

Token amounts implied by L at entry, from ILMath.getAmountsForLiquidity.

maxIL · bigint

The MaxIL cap (6-dec numéraire) — both the payout ceiling and the unit of risk.

inRange · boolean

sqrtP0 >= sqrtPa && sqrtP0 <= sqrtPb — the on-chain in-range gate. createSwap rejects out-of-range entries.

inRange:false is informative, not an error. It tells you the on-chain create call will revert because P0 is outside [Pa, Pb]. Why: Inflexion hedges in-range convexity only — out-of-range there is no in-range IL to transfer, so the in-range invariant is enforced at creation. Mitigation: surface “out of range — not eligible” in the UI and offer the LP a position whose range still brackets spot.

---

listEligiblePositions

Enumerates an owner’s Uniswap v3 NFTs and prices each one across the requested durations. It reads balanceOf / tokenOfOwnerByIndex / positions from the NPM, then runs resolveGeometry per (position × duration) pair.

owner · 0x${string} · required

The wallet whose positions to enumerate.

opts.durations · number[]

Durations (seconds) to price each position against. Defaults to the market grid’s durations.

returns · EligiblePosition[]

One row per (position × duration). Each row carries the resolved geometry plus eligibility flags. Returns an empty array if the NPM is unreachable. Per row, inRange is undefined when the oracle is degraded for that price (the position can’t be priced this block).

---

previewPremium

The load-bearing method: “what dollar premium will I be charged on THIS position if I sign in the next block?” It is the best-of {pool, MM} quote, both capped at the same MaxIL.

tokenId · bigint · required

marketId · 0x${string} · required

opts.poke · boolean

If true, sends a VolOracle.poke(token) write before reading to refresh the σ_ref EWMA (otherwise pure read).

opts.engineBaseUrl · string

Override the Path-B quote engine base for this call.

returns · Priceable<PreviewResult>

On success the full pricing breakdown; on oracle degradation, NotPriceable.

Show PreviewResult

marketId · 0x${string}

maxIL · bigint

The shared cap both paths are bounded by.

fairPremium · bigint

The on-chain Φ-sum fair value (numéraire) — read, never reimplemented off-chain.

fairRateWad / sigmaRefWad · bigint

The fair rate and reference vol used.

premiumA · bigint

Path-A pool premium = ceil(fairPremium·(1+totalLoad)) capped at MaxIL.

premiumB · bigint | undefined

Best live signed MM quote, capped at the same MaxIL. Undefined if the engine is unreachable or no quote beats the pool.

best · bigint

The cheaper of the two.

path · 'A' | 'B'

Which rail produced best.

How the premium is built:

1. Read the on-chain fair value

   FairValueOracle.fairPremium(token, aWad, bWad, durationSeconds, maxIL) → (premium, fairRateWad, sigmaRefWad). The Φ-sum is never reimplemented off-chain.

2. Read pool inventory + params

   ConvexityVault.inventory() → (total, locked, free, util, conc) and loadParams().

3. Finish the load stack client-side (the single permitted duplication)

   totalLoad = cvamm.totalLoadWad(sigmaRef, util, conc, params), then premiumA = cvamm.premiumFromLoad(fairPremium, totalLoad) capped at MaxIL — byte-equal to _pricePathAFromFair on-chain because the deployed CvammPricing lib is delegatecall-only.

4. Fetch the best MM quote (best-effort)

   GET ${engineBaseUrl}/quote?marketId=… for the cheapest live signed quote; premiumB = cvamm.pathBPremium(fairPremium, loadBps, maxIL) capped at the same MaxIL. An unreachable engine leaves premiumB undefined and routes Path A — never an error.

5. Pick the cheaper, then fire telemetry

   best/path = min(premiumA, premiumB). A fire-and-forget telemetry ping (latent-demand Signal 4) is sent — never awaited, never throws.

previewPremium performs no approvals and sends no transaction (unless poke:true). Treat it as the quote you snapshot to compute maxPremium immediately before calling buyProtection.

---

getPayoffCurve

Computes the LP’s settlement payoff across a grid of terminal prices, with the cap applied. Drives the payoff chart in the protect flow.

tokenId · bigint · required

marketId · 0x${string} · required

opts.points · number

Number of grid points across the sqrt-price range. Higher = smoother curve.

returns · Priceable<PayoffCurve>

On success, the curve of (price, il, payout) where payout = min(il, MaxIL), evaluated via ILMath.computeIL over a sqrt-price grid. NotPriceable if the oracle is degraded.

The cap is applied here, so the curve flattens at MaxIL — the visual proof that no bad debt is structural: the LP never claims more than the underwriter’s locked collateral.

---

buyProtection

The LP write. Sends approvals (by default) and fires the chosen create call on InflexionCore.

tokenId · bigint · required

The position NFT to protect.

marketId · 0x${string} · required

Required for the Path-A force path; for routed/Path-B the marketId travels inside the quote.

maxPremium · bigint · required

The LP’s slippage guard (numéraire raw, 6-dec). The on-chain create reverts if the routed premium would exceed it.

quote · SignedQuote

An MM quote envelope. Required when escapeHatch:'B'; optional for routed (omit → the EMPTY_QUOTE sentinel → router falls back to the pool).

signature · 0x${string}

The EIP-712 signature for quote.

escapeHatch · 'A' | 'B'

Force a specific rail. Omit for routed best-of (recommended). See the create-call matrix below.

approve · boolean · default: "true"

When not explicitly false, sends NPM + dUSDC approvals to InflexionCore before the create call.

returns · Hex

The create transaction hash. Throws a clear error if no wallet client is configured.

Which create call fires

escapeHatch	Contract fn	Notes
undefined (default)	createSwapRouted(quoteTuple, signature, tokenId, maxPremium)	best-of {pool, MM}. A missing quote uses the EMPTY_QUOTE sentinel (mm == address(0), empty signature) so the router falls back to the pool.
'A'	createSwapPathA(marketId, tokenId, maxPremium)	force the always-on cvAMM pool.
'B'	createSwap(quoteTuple, signature, tokenId, maxPremium)	force a specific signed MM quote; requires {quote, signature} or throws.

createSwapRouted never reverts on a bad MM quote. A malformed or stale quote falls back to the pool on-chain. Only the executed rail mutates nonce / capacity / lock — see routing.

Approvals — the spender is InflexionCore

When buyProtection runs with approve not explicitly false, the SDK sends two approvals before the create call:

• NPM approve(core.inflexionCore, tokenId) — the position NFT to the core.
• dUSDC — read allowance(account, core.inflexionCore); if < maxPremium, send approve(core.inflexionCore, maxPremium) — spender is InflexionCore.

---

getProtectionStatus

Reads the live state of an existing protection (swap): status enum, which rail underwrote it, and the IL-to-date with the cap applied.

swapId · bigint · required

The id returned in the SwapCreated event from buyProtection.

returns · ProtectionStatus | {available:false, reason}

available:false if the swap id is unknown.

Show ProtectionStatus

status · number

0 = UNINITIALIZED, 1 = ACTIVE, 2 = SETTLED.

isPathA · boolean

mm == convexityVault — i.e. underwritten by the pool.

ilToDate · Priceable<{ il, payout, capHit }>

The realized IL so far, the capped payout, and capHit = payout < il. Itself a Priceable — it degrades if the oracle is down without failing the whole status read.

noBadDebtFull · true

The Claim-A marker (qualified — see disclosure above).

ilToDate.payout is computed from settlePreview via simulateContract against the oracle-derived spot, so it mirrors exactly what settle would pay this block.

---

getClaimableFees

Estimates the Uniswap fees the LP can still collect on the underlying position, from the NFT’s checkpointed tokensOwed0/1.

swapId · bigint · required

returns · ClaimableFees | {available:false}

{ available:false } if the swap is unknown; otherwise the checkpointed owed amounts.

This figure UNDER-states actual claimable fees. Why: tokensOwed0/1 only reflects fees checkpointed at the last NFT interaction, not fees accrued since. Mitigation: the precise figure needs the subgraph’s fee accounting, which is pending; until then treat this as a conservative lower bound and label it as such in the UI.

Structures ship from day one; the full DYNAMICS (pool-vs-MM spread as a forward-vol signal) mature with multiple competing MMs and volume. The dataset begins at the single redeploy; the off-chain telemetry halves begin at the first interaction logged.

What Inflexion offers today is the architecture and the first public view into the microstructure of the DeFi LP volatility-risk premium — not yet a mature dataset:

• Structures are present day-one. All five non-circular behavioral signals are defined and queryable from launch.
• Dynamics mature with volume. The richer signal — the pool-vs-MM spread read as a forward-vol indicator — only sharpens once multiple market makers compete and real flow accumulates.
• The dataset begins at the single redeploy, and the off-chain telemetry halves begin at the first interaction logged. History is served live from the subgraph via the API; if a backing (subgraph URL / RPC / telemetry) is absent, surfaces degrade to a typed pending state — never an error.

---

settle

The LP (or anyone) settlement write. Recovers the swap’s expiry, finds the bracketing Chainlink round (round-walk, or your hint), then calls Core.settle to pay the LP min(realized_IL, MaxIL) from the underwriter’s collateral.

swapId · bigint · required

opts.hintRoundId · bigint

A Chainlink round id that brackets expiry. If omitted, the SDK walks Chainlink rounds backwards to find it (findHintRoundId).

returns · Hex

The settlement transaction hash. Throws a clear error if no wallet client is configured.

settle always succeeds within the liveness window (invariant I8): expiry + LIVENESS_WINDOW + MAX_STALENESS + GRACE_PERIOD. The round-walk + grace period is the oracle-deadlock fork resolution — a late or briefly-stale feed cannot strand a settlement.

---

autoProtect

Orchestrates the whole flow — list → preview → buy — across an owner’s eligible positions, with ACTIVE-protection dedupe. Never throws: every row is a structured success / skipped / error result.

owner · 0x${string} · required

The wallet whose positions to auto-protect.

maxPremium · bigint

Per-position premium ceiling (numéraire raw). Rows whose best premium exceeds it are skipped.

durations · number[]

Durations to consider per position.

dryRun · boolean

If true, prices and plans but sends no transaction — pure read.

returns · AutoProtectResult[]

One row per candidate. Each row is a success (with txHash), a skipped row (already ACTIVE, out of range, or over maxPremium), or an error row. The method scans swaps / nextSwapId for existing ACTIVE protection to avoid double-buying.

behavior · W (unless dryRun)

Writes one create tx per actionable row. Requires a wallet unless dryRun:true.

---

poke

Refreshes the σ_ref EWMA for a token before pricing, by calling VolOracle.poke(token).

token · 0x${string} · required

The volatile token whose σ_ref to refresh.

returns · Hex

The poke transaction hash. Throws if no wallet client is configured.

Use this (or previewPremium({ poke:true })) when σ_ref may be stale and you want the freshest fair value before signing.

---

findHintRoundId

A read helper that walks Chainlink rounds backwards from latest to find the round that brackets a target timestamp — the hintRoundId settle needs.

oracleToken · 0x${string} · required

The token whose Chainlink feed to walk.

expiry · bigint · required

The target timestamp (the swap’s expiry).

opts.maxWalk · number

Cap on how many rounds to walk backwards.

returns · bigint

The bracketing round id. On an un-fetchable phase boundary it returns the best available round rather than throwing.

---

Worked example — preview, buy (routed), settle

import { createInflexionSdk, demo, tokens } from '@inflexion/sdk'

const sdk = createInflexionSdk({ publicClient, walletClient, engineBaseUrl })
const lp = sdk.lp

// 1. Price it — Path-A pool + best engine MM quote, both capped at MaxIL.
const preview = await lp.previewPremium(demo.lpPositionTokenId, demo.marketId_fee500_7d)
if (!preview.priceable) throw new Error(`not priceable: ${preview.reason}`)
console.log(preview.best, preview.path)        // e.g. 8_930_000n (=$8.93), 'B'

// 2. maxPremium = best + 1% slippage (raw 6-dec; round up).
const maxPremium = (preview.best * 10_100n) / 10_000n + 1n

// 3. Buy — default approvals (NPM approve + dUSDC approve to InflexionCore).
const txHash = await lp.buyProtection({
  tokenId: demo.lpPositionTokenId,
  marketId: demo.marketId_fee500_7d,
  maxPremium,
  // omit quote/signature → createSwapRouted picks the cheaper of pool vs MM on-chain
})

// 4. Inspect, then settle after expiry (round-walk finds the bracketing round).
const status = await lp.getProtectionStatus(2n)
if (status.available && status.ilToDate.priceable) {
  console.log(status.ilToDate.payout, status.ilToDate.capHit)   // capped payout, cap-hit flag
}
const settleTx = await lp.settle(2n)

To route a specific MM quote (Path B), pass { quote, signature, escapeHatch: 'B' } where quote is the SignedQuote and signature the EIP-712 sig.

Approvals & decimals at a glance

Action	Spender	Approval flow	Decimals
buyProtection	InflexionCore	NPM approve(core, tokenId) + dUSDC approve(core, maxPremium) (auto unless approve:false)	dUSDC 6-dec
settle / poke	—	no approval	—

Framing that must stay exact

• In-range convexity hedge, not “IL insurance”. Entry requires Pa ≤ P0 ≤ Pb; the inRange gate rejects out-of-range at creation. See the hedge.
• Payout = min(realized_IL, MaxIL); the cap is load-bearing for no bad debt. getPayoffCurve / ilToDate apply it.
• The Φ-sum is read on-chain, never reimplemented — only the deterministic load stack is mirrored off-chain (parity-locked), because the deployed lib is delegatecall-only.

Related

LpClient guide

The narrative walkthrough of the LP surface, with the routing flow explained.

Degradation envelopes

Priceable / Degraded / WriteResult — the full envelope taxonomy.

Lifecycle

Create → active → settle, end to end.

Routing

How createSwapRouted picks pool vs MM and never reverts on a bad quote.