> ## Documentation Index
> Fetch the complete documentation index at: https://inflexion.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# SDK overview
> What @inflexion/sdk is — the typed access layer over the live deployment, its two design properties (reads degrade, writes throw or defer without a wallet), its foundation + five surfaces + quote helpers, and how it surfaces the three pillars.
**`@inflexion/sdk` is the typed access layer over the live deployment.** It is the **only** layer that holds a signer, and the only one that can answer the load-bearing question — *"what dollar premium will I be charged on **this** position if I sign in the next block?"* — by combining a fresh on-chain `FairValueOracle` read with the position's geometry. Everything in this section is built on the foundation, five stakeholder surfaces, and EIP-712 quote helpers described below.
The SDK wraps the [live Arbitrum Sepolia deployment](/reference/deployments) (chainId `421614`, fresh full redeploy 2026-06-05) and exposes it as one ergonomic object: a single factory call wires a read client and an optional write client into all five surfaces at once. No contract address is ever passed in — every address loads from the on-chain address registry.
***
## The two design properties
These run through the whole package. If you remember nothing else about the SDK, remember these two — they are what make it safe to use from a wallet-less server, a degraded-RPC browser tab, or a UI that loads against a backing that is momentarily unreachable.
Anything that needs a reverting oracle, an absent rich event, or an unreachable history source returns a **typed degraded envelope** — never throws.
With no `walletClient`, the SDK still constructs. Writes either throw a **clear error on call** or return a **deferred result** carrying the unsigned tx — the only place a missing signer surfaces.
### 1 — Reads degrade gracefully
Every read that can fail returns a **typed degraded envelope** instead of throwing. There are three shapes, and the type system forces you to handle the failure branch before you can touch the data:
| Envelope | Success branch | Failure branch | Used by |
| - | - | - | - |
| `Degraded` | `{ available: true } & T` | `{ available: false, reason }` | vault state, position, regime, surface σ\_ref |
| `Priceable` | `{ priceable: true } & T` | `{ priceable: false, reason, detail? }` | anything needing the live price $P_0$ |
| `ApiPending` | — | `{ available: false, reason: 'no-history-source', endpoint, query, detail }` | all DataClient history methods |
```ts theme={null}
// The compiler will not let you read .geometry until you check the branch.
const g = await sdk.lp.resolveGeometry(tokenId, marketId)
if (!g.priceable) {
// reason ∈ { 'oracle-degraded', 'market-unknown', 'position-unknown', ... }
console.warn('not priceable:', g.reason)
} else {
console.log(g.geometry.maxIL) // safe — narrowed to the success branch
}
```
The `reason` is drawn from a closed union, `DegradeReason ∈ { oracle-degraded, no-rpc, rich-events-absent, no-history-source, vol-uninitialized, market-unknown, position-unknown }`. This is the discipline that lets the UI render a typed "pending" or "oracle degraded" state instead of catching an exception — a degraded read is a **value**, not a thrown error.
The SDK **never fabricates history**. History surfaces are served live from the subgraph via the [hosted API](https://inflexion-backend.onrender.com). Should a history source be momentarily unreachable, `ApiPending` even names the API route and the exact query that *would* be sent — so the UI can show "coming from ``" and degrade with zero re-derivation. See [degradation](/sdk/degradation) for the full cheat-sheet.
### 2 — Writes throw or defer without a wallet
The factory always constructs, even with no signer (`makeWalletClient` returns `undefined` rather than crashing). What happens when you then call a write depends on the surface — and the difference is deliberate:
`lp.buyProtection`, `lp.settle`, `lp.poke`, and `mm.cancelNonces` throw a **clear error on call**. These are direct, user-driven transactions: there is no sensible "deferred" semantics for "buy this protection now", so a missing signer is treated as a hard, explicit error at the call site — never at construction.
`depositor.deposit`, `requestWithdrawal`, and `withdraw` return a typed `WriteResult` with `status: 'deferred-no-wallet'` carrying the **unsigned tx** for an external signer. This suits server-side and custody flows where the SDK builds calldata that something else signs. The full status union is `'sent' | 'deferred-no-wallet' | 'error'`.
```ts theme={null}
// No wallet → DepositorClient builds, but does not send.
const sdk = createInflexionSdk({ publicClient }) // read-only
const res = await sdk.depositor.deposit('junior', 10_000_000_000n)
// res.status === 'deferred-no-wallet'; res.tx is the unsigned calldata.
// No wallet → LpClient throws on the write call (not at construction).
await sdk.lp.buyProtection({ tokenId, marketId, maxPremium }) // throws a clear error
```
Most write methods also have a `build*` sibling (`depositor.buildDeposit`, `mm.buildCancelNoncesTx`, …) that returns raw `{ to, data, value }` calldata for full external-signing control. See [guardrails](/sdk/guardrails) for the write-safety model.
***
## The foundation + five surfaces + quote helpers
The SDK is the **foundation** (addresses, ABIs, viem client factory, shared types, tuple decoders, `resolveMarket`, the `CvammPricing` TS port under `cvamm`) **plus** five stakeholder surfaces **plus** the re-exported EIP-712 quote helpers.
### The foundation
Imported flat from the package root and re-exported wholesale:
* **Addresses, decimals, units** — `import { core, stylus, libs, tokens, demo, chainlink, uniswap, npm, CHAIN_ID } from '@inflexion/sdk'`. dUSDC = **6 decimals** (the numéraire — every premium, amount, `V0`, `maxIL`, and collateral figure is a 6-dec raw bigint, `1 dUSDC = 1_000_000n`); dWETH = 18; Chainlink feeds = 8; `WAD = 1e18` for ratios. See [addresses & units](/sdk/addresses-units) and [decimals & units](/reference/decimals-units).
* **ABIs + a viem client factory** — `makePublicClient` / `makeWalletClient` with env-fallback RPC and key resolution.
* **Shared types + tuple decoders** — the degradation envelopes above, plus decoders for the compact on-chain structs.
* **`resolveMarket`** — recovers a swap's `marketId` (a `SwapRecord` carries none on-chain) by reproducing `keccak256(abi.encodePacked(token0, token1, fee, uint32(expiry − createdAt)))`.
* **The `cvamm` math port** — namespaced to avoid clobbering type names; the **permanent, parity-locked** off-chain mirror of the deployed `CvammPricing` load library (see below and [cvamm port](/sdk/cvamm-port)).
### The five surfaces
One factory call wires all five at once. Each carries exactly one stakeholder's claim — and **claims are never merged**:
**Buy in-range IL protection (Claim A).** Price (`previewPremium`), buy (`buyProtection`, routed best-of pool vs MM), track (`getProtectionStatus`), and settle. Carries `noBadDebtFull: true`, qualified.
**Passive / active underwriting (Claim B).** Deposit to the [senior or junior tranche](/concepts/tranches), read vault state and your position, withdraw under cooldown. Every result carries `capitalNotGuaranteed: true`.
**Path-B market making.** Price a market, get the geometry-free "pool load to beat", sign firm EIP-712 quotes (with I10 + below-pool guards), stream a requote loop, read the book and capacity.
**The data moat.** One live surface (`getCurrentLoadSurface`) plus the typed-pending history surfaces for the five behavioral signals. Read-only.
**Read-only analytics (the fifth surface).** Greeks (δ/γ/vega/θ) and a three-leg hedge suggestion, all derived from the protocol's **own deployed math** — no parallel pricing model, and it **never submits a transaction**.
The factory returns `{ publicClient, walletClient?, chainId, lp, depositor, mm, data, greeks, hedge }`.
| Surface | Class | Claim it carries | Default writes spender |
| - | - | - | - |
| **LpClient** | LP buys IL protection | `noBadDebtFull: true` (qualified) | **InflexionCore** (`buyProtection`) |
| **DepositorClient** | passive/active underwriter | `capitalNotGuaranteed: true` | **ConvexityVault** (`deposit`) |
| **MmClient** | Path-B market making | (sign-only + cancel) | **InflexionCore** (`cancelNonces`); collateral is a separate UnderwriterVault flow |
| **DataClient** | the data moat | — (read-only) | none |
| **GreeksEngine + HedgeSuggester** | read-only analytics | — (read-only) | none (never sends a tx) |
**Claim A and Claim B are separate claims that the SDK never merges.** Claim A — *LPs are always paid; no bad debt in FULL (I1), qualified* — lives on the LP surface only. Claim B — *depositor/MM capital is **not** guaranteed* — lives on the depositor surface only. Both are exported verbatim as `LP_CLAIM_A` / `DEPOSITOR_CLAIM_B` so the UI renders the right one in the right place.
### The quote helpers
The EIP-712 `SignedQuote` machinery is owned by the engine (the single source of truth) and **re-exported** through `@inflexion/sdk` and `@inflexion/sdk/quote`. The field order, types, and domain must match `InflexionCore.SIGNED_QUOTE_TYPEHASH` exactly or `createSwap` / `createSwapRouted` rejects the signature. Helpers include `signQuote`, `quoteDigest`, `verifyQuote` / `recoverQuoteSigner`, `encodeQuote` / `decodeQuote`, plus the `SignedQuoteTypes` / `quoteDomain` building blocks used for browser (wagmi) signing. Full reference: [quote signing](/integrate/quote-signing) and [the MM client](/sdk/mm-client).
***
## How the SDK surfaces the three pillars
The SDK is not a new pricing system — it is the typed window onto the [three pillars](/concepts/three-pillars). The mapping is exact and worth holding:
The SDK **reads** the exact closed-form Φ-sum from the Stylus [`FairValueOracle`](/concepts/fair-value) (`fairPremium` / `fairRate`) and **never reimplements it off-chain**. It only re-evaluates the deterministic, `pure` **load** stack client-side via the parity-locked [`cvamm` TS port](/sdk/cvamm-port) — the single duplication the architecture permits, and only because the deployed `CvammPricing` library is **delegatecall-only** (a direct `eth_call` reverts).
`DepositorClient` is the surface onto the always-on, signature-free [Path-A underwriter](/protocol/path-a-cvamm) (`ConvexityVault`) — deposits, tranche state, and the load-decomposed pool floor. The pool's "load to beat" is also a first-class MM signal via `mm.getPoolLoadToBeat` / `streamPoolLoadToBeat`.
`MmClient` produces firm EIP-712 signed quotes with **no last look** (the I10 + below-pool guards live in `mm.signQuote`). On the LP side, `lp.previewPremium` and `lp.buyProtection` route the [cheaper of pool vs MM](/protocol/routing): `createSwapRouted` picks the best-of on-chain and falls back to the pool on a missing or bad quote — it **never reverts on a bad MM quote**.
```ts theme={null}
// The three pillars in one preview call:
const preview = await sdk.lp.previewPremium(demo.lpPositionTokenId, demo.marketId_fee500_7d)
if (preview.priceable) {
preview.fairPremium // Pillar 1: read on-chain Φ-sum (never reimplemented)
preview.premiumA // Pillar 2: pool floor = fairPremium + parity-locked load stack
preview.premiumB // Pillar 3: best live signed MM quote (undefined if none beat the pool)
preview.best // the cheaper of the two; preview.path ∈ 'A' | 'B'
}
```
***
## One-call construction
`createInflexionSdk(config)` wires one public (read) client + one optional wallet (write) client into all five surfaces. With **no arguments at all**, it still constructs: env-resolved RPC and key, with graceful degradation if either is absent.
```ts Browser / wagmi (recommended) theme={null}
'use client'
import { useMemo } from 'react'
import { usePublicClient, useWalletClient, useAccount } from 'wagmi'
import { createInflexionSdk, type InflexionSdk } from '@inflexion/sdk'
export function useInflexionSdk(): InflexionSdk {
const publicClient = usePublicClient() // reads
const { data: walletClient } = useWalletClient() // writes (undefined until connected)
const { address } = useAccount()
return useMemo(
() =>
createInflexionSdk({
publicClient, // overrides rpcUrl/transport
...(walletClient ? { walletClient } : {}), // omit → writes throw a clear error on call
chainId: 421614, // EIP-712 chainId for quote signing
engineBaseUrl: process.env.NEXT_PUBLIC_ENGINE_URL,
fetchImpl: fetch,
}),
[publicClient, walletClient, address],
)
}
```
```ts Server / key-based theme={null}
import { createInflexionSdk } from '@inflexion/sdk'
const sdk = createInflexionSdk({
rpcUrl: process.env.ARBITRUM_SEPOLIA_RPC,
privateKey: process.env.DEPLOYER_PRIVATE_KEY as `0x${string}`, // → funded write client
engineBaseUrl: process.env.ENGINE_URL,
})
// sdk.lp / sdk.depositor / sdk.mm / sdk.data / sdk.greeks / sdk.hedge are all wired.
```
In the browser pattern, `walletClient.account` is used directly — wagmi's `useWalletClient()` already carries `.account` and `.chain`, so you pass no explicit `account`. The full config table and resolution order live in [getting started](/sdk/getting-started).
**No address is ever passed to the factory.** Every contract address loads from the [deployment registry](/reference/deployments). Import the symbols you need (`core`, `tokens`, `demo`, …) rather than hardcoding — see [addresses & units](/sdk/addresses-units).
***
## What is live today
The SDK is fully usable against the live deployment. Direct RPC surfaces are served from the chain; history and aggregate surfaces are served live from the subgraph via the [hosted API](https://inflexion-backend.onrender.com):
| Live from RPC (direct) | Live from the subgraph (via the hosted API) |
| - | - |
| premium preview, current load surface, σ\_ref | all DataClient history (load-surface, quote-competition, demand, NAV, net-gamma) |
| market pricing, vault state, protection status | precise `QuoteFilled` fill attribution |
| position geometry, `getBook` (on-chain scan) | full fee accounting |
| `watchFills` (coarse log poll) | NAV history |
**Graceful degradation is a design property, not the current state.** All history and aggregate surfaces (`getLoadSurfaceHistory`, `getQuoteCompetition`, `getNavHistory`, …) are served live from the subgraph via the hosted API. If a backing (the `SUBGRAPH_URL`, the RPC, or a telemetry sink) is ever unset or unreachable, these methods return `ApiPending`, which **names the route and the exact query** that would be sent — the UI renders "coming from ``" and the SDK never fabricates history. See [degradation](/sdk/degradation). On the free hosting tier the backend sleeps after \~15 min idle, so the first call after a quiet period may incur a cold start.
**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.
***
## The claims, stated correctly
The SDK carries these as first-class, never-merged flags. They are reproduced here because every consumer of the SDK must state them with their full qualifying clauses.
**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.
**Depositor capital is NOT guaranteed: the junior tranche is first-loss; the senior tranche is structurally protected from underwriting loss only, not systemic tail.**
Underwriting capital — whether supplied to the pooled cvAMM vault (Path A) or posted directly by a market maker (Path B) — is **at risk**:
* **Junior tranche — first-loss.** Junior depositors absorb underwriting losses first and buffer the senior tranche.
* **Senior tranche — protected from underwriting loss, exposed to the systemic tail.** The senior tranche is structurally shielded from ordinary underwriting loss while junior capital buffers, but it still takes the systemic tail once the junior buffer is exhausted.
No-bad-debt is a guarantee to the **LP being paid** (see the FULL-mode payout clause), **not** a guarantee that depositor or MM capital is preserved.
***
## Where to go next
Install, the full `InflexionSdkConfig` field table, and the construction/degradation resolution order.
The address symbols, decimals (dUSDC = 6, dWETH = 18, feeds = 8, WAD = 1e18), and `sqrtPriceX96` conversions.
Price, buy (routed best-of), track, and settle in-range IL protection.
Underwrite via the cvAMM tranches; vault state and position reads carry Claim B.
Per-market firm quotes, the pool load to beat, the requote loop, and capacity.
The live load surface and the five behavioral signals of the data moat.
Read-only greeks and the three-leg hedge — derived from the protocol's own math.
The full envelope cheat-sheet and the write-safety model.
For the live contract addresses, see the [deployments reference](/reference/deployments).
**Network:** Arbitrum Sepolia · **chainId** `421614` · **deploy block** `274081134` (subgraph startBlock) · **deployed** 2026-06-05
## Core protocol
| Contract | Address | Role |
| - | - | - |
| InflexionCore | `0xC19865cF8403F59B8Eca835833aFEe3Aa8DA4848` | Main entry point — quotes, createSwap, settlement |
| ILVault | `0x9f7615Aca943832977CEf3ac1862fD48B87b7664` | Holds LP premiums and protocol IL accounting |
| UnderwriterVault | `0x4Fb459F3393D206c2b7faD7f0fC9C35a78348D64` | Market-maker (Path B) collateral deposits |
| ConvexityVault | `0xDE2fFeBA2E6A18f3A53D43EC0fCCD299158eC30d` | Pooled cvAMM (Path A) underwriter collateral |
| Treasury | `0x96455C9b00D530BD0629b71B674298440328b1Dd` | Protocol fee recipient (also deployer) |
## Stylus & libraries
| Contract | Address | Role |
| - | - | - |
| FairValueOracle (Stylus) | `0x98a6aa75108b70fc0794bc3b87efe0ae99d5d52c` | Rust/WASM fair-premium pricing (set-once init to live VolOracle) |
| ILMath | `0x7e90362bc6Df9cb5faA13952e07853ab16c77bd2` | Core impermanent-loss math |
| TickMath (library) | `0xbf02bbc82e0fb1a4b9828bb90fc9dd9e97578965` | Tick ↔ sqrtPrice conversions (delegatecall) |
| CvammPricing (library) | `0x4a053d29a55a64172140f9ebbc27c321c0ba2b53` | Path-A pool pricing components (delegatecall) |
| SwapMath (library) | `0xf7be9745b6768d06a18c386c6db5c8cb065ba314` | Swap math helpers (delegatecall) |
| QuoteVerification (library) | `0x74819eed322f3e1a2dc10bb0d3cae50078d90807` | EIP-712 quote signature verification (delegatecall) |
## Oracles
| Contract | Address | Role |
| - | - | - |
| OracleManager | `0x2c18147B6ec75dcb330d9A48B6B96a4d1a8b529b` | Chainlink feed router, staleness & sequencer checks |
| VolOracle | `0xfdEafBB381192FC5337499d041eaead04d565Ed9` | Realized-volatility reference (sigma\_ref) |
## Uniswap
| Contract | Address | Role |
| - | - | - |
| UniswapV3Factory | `0x248AB79Bbb9bC29bB72f7Cd42F17e054Fc40188e` | v3 pool factory |
| NonfungiblePositionManager | `0x6b2937Bde17889EDCf8fbD8dE31C3C2a70Bc4d65` | LP position NFTs |
| SwapRouter02 | `0x101F443B4d1b059569D643917553c771E1b9663E` | Swap routing |
| QuoterV2 | `0x2779a0CC1c3e0E44D2542EC3e79e3864Ae93Ef0B` | Off-chain swap quoting |
## Chainlink feeds
| Contract | Address | Role |
| - | - | - |
| ETH / USD | `0xd30e2101a97dcbAeBCBC04F14C3f624E67A35165` | Price feed (8 dec, \~120s heartbeat) |
| BTC / USD | `0x56a43EB56Da12C0dc1D972ACb089c06a5dEF8e69` | Price feed (8 dec, \~120s heartbeat) |
| ARB / USD | `0xD1092a65338d049DB68D7Be6bD89d17a0929945e` | Price feed (8 dec, 86400s heartbeat) |
| USDC / USD | `0x0153002d20B96532C639313c2d54c3dA09109309` | Price feed (8 dec, 86400s heartbeat) |
## Demo tokens / pool / LP
| Contract | Address | Role |
| - | - | - |
| WETH9 | `0x980B62Da83eFf3D4576C647993b0c1D7faf17c73` | Canonical Arbitrum Sepolia WETH (18 dec) |
| USDC (Circle) | `0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d` | Circle native testnet USDC (6 dec) |
| dWETH (demo) | `0xA8C07E1B245B346c5D1910c5055Efe67bF9E7D1D` | Mock WETH, oracle-priced via Chainlink ETH/USD (18 dec) |
| dUSDC (demo) | `0xB89630Dc6e020ae2A84aE72b7d9EEDBDfb2C544d` | Mock USDC numeraire (6 dec) |
| Demo pool (dWETH/dUSDC, fee 500) | `0xfE1Eb4D5796a350B13852F822B3E6a9fDbb858a5` | Seeded v3 pool, tokenId 3218 \~\$100k unprotected LP |
## Lifecycle swaps
| Contract | Address | Role |
| - | - | - |
| Market maker (demo signer) | `0xe632B215120dD43A719458487bA3e03638fec953` | Path-B underwriter; deposited 5,000 dUSDC, own collateral paid settlement |
Live create→settle lifecycle (2026-06-05, short 300s fee-500 market `0xb8bbd684f213d5833886ade7b531a6949d85522249881a2b5d46a5cc76e439c2`):
* **Path A (cvAMM convexity)** — swapId 1, LP tokenId 3220 · V0 \$270,531.28 · MaxIL \$1,669.24 · premium \$9.70 (0.58% of MaxIL) · settled payout \$148.64 from ConvexityVault.
* **Path B (MM routing)** — swapId 2, LP tokenId 3221 · MM beat cvAMM (\$8.93 vs \$13.80) · MaxIL \$3,215.65 · MM collateral locked \$3,215.65 · settled payout \$245.66 from MM collateral.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.