Repo layout & conventions

The monorepo package map — contracts, engine, SDK, subgraph, API, web, docs, quant — plus the language/version conventions, and why Stylus builds are WSL2-only.

Inflexion is a single pnpm + cargo workspace: one repository holds the on-chain code (Solidity + a production Rust/Stylus pricer), the off-chain Path-B relayer, the typed SDK, the subgraph, the public API, the dApp, these docs, and the quant model. This page is the map — what lives where, the language and version conventions enforced across packages, and the one platform constraint worth flagging up front: the Stylus toolchain builds only on WSL2/Linux.

The package map

The repo splits into packages/* (libraries and services), apps/* (the two deployed front-ends), and a handful of top-level support directories.

packages/contracts

Foundry — all on-chain code. Solidity stack + the Rust/Stylus FairValueOracle, the test suites, and the deploy script.

packages/engine

The off-chain Path-B matching relayer (Node/TS): WS quote intake, ranking, signed-payload API. Plus the MM bot.

packages/sdk

@inflexion/sdk — the LP / MM-quoter / cvAMM-depositor / data surfaces. The integration entry point.

packages/subgraph

The Graph subgraph (schema + mappings). Deployed and indexing on The Graph Studio.

packages/api

Public REST API (Railway/Fly) over the subgraph, with live-read fallbacks.

apps/web

The dApp: React + Vite, wagmi/viem, RainbowKit, Apollo, shadcn/ui, Recharts.

apps/docs

docs.inflexion.xyz — this Mintlify site.

quant

Python → the cvAMM params schema; gates PARTIAL. The Monte Carlo that produces every load/skew constant.

The full annotated tree:

repository tree

packages/contracts/   Foundry — Solidity + Stylus; test/ (unit, fork, Invariants.t.sol); script/Deploy.s.sol
  stylus/ILMath/      Rust Stylus IL math (REJECTED benchmark artifact — NOT deployed; revm CI cross-check only)
  stylus/FairValueOracle/  Rust Stylus PRODUCTION fairRate Φ-sum pricer (DEPLOYED)
packages/engine/      Off-chain Path-B matching relayer (Node/TS): WS quote intake, ranking, signed-payload API
packages/sdk/         @inflexion/sdk — LP / MM-quoter / cvAMM-depositor / data surfaces
packages/subgraph/    The Graph subgraph (schema + mappings) — DEPLOYED + indexing on The Graph Studio
packages/api/         Public REST API (hosted on Render) over the subgraph
apps/web/             React + Vite, wagmi/viem, RainbowKit, Apollo, shadcn/ui, Recharts
apps/docs/            docs.inflexion.xyz (Mintlify)
quant/                Python → cvAMM params schema (params.cvamm.schema.json); gates PARTIAL; legacy/ = multi-asset
docs/                 Root-level: MATH, SECURITY, INTEGRATION, API
scripts/              Cross-platform helpers (.sh + .ps1)
deployments/          Per-network address registries (arbitrum-sepolia.json, etc.)

Package responsibilities

Each package owns one surface of the protocol. The dependency direction is roughly: contracts publish state and prices on-chain → the subgraph indexes them → the API serves them → the SDK reads contracts (live) and the API/subgraph (history) → the dApp and integrators consume the SDK. The engine sits beside this as the Path-B signing rail.

packages/contracts — the on-chain core

Foundry project holding the entire on-chain system. The Solidity stack is InflexionCore (the state machine — createSwapPathA / createSwap / createSwapRouted, CEI settlement, the 10 invariants), OracleManager, VolOracle, ILMath (the production settle-path math), ILVault, UnderwriterVault, and ConvexityVault. Tests live in test/ — unit, fork, and Invariants.t.sol; the broadcast is script/Deploy.s.sol.

Two Rust/Stylus crates live under stylus/:

• stylus/FairValueOracle/ — the DEPLOYED, production closed-form fairRate Φ-sum pricer.
• stylus/ILMath/ — a rejected benchmark artifact, not deployed; it survives only as a revm CI cross-check. The production IL math is the Solidity ILMath, not this crate.

See Protocol overview for how these compose.

packages/engine — the Path-B relayer

The off-chain matching relayer for Path B (Node/TS): WebSocket quote intake from MMs, ranking, and a signed-payload API the dApp/SDK calls. It is a convenience and discovery layer, not a trust layer — every quote is a firm EIP-712 signature verified on-chain, and capacity/replay defense is on-chain authoritative (I7). The engine also ships the MM bot and the two day-one telemetry sinks (DEMAND_LOG, COMPETITION_LOG) that feed two of the five moat signals. See the engine architecture.

packages/sdk — @inflexion/sdk

The typed integration entry point, with four surfaces: LP, MM-quoter, cvAMM-depositor, and data. It hardcodes nothing — addresses.ts loads the deployment registry and re-exports typed groups. It never reimplements the Φ-sum off-chain — it reads the on-chain FairPremium; the only off-chain duplication permitted is the load math, kept as a parity-locked TS mirror because the deployed Solidity libraries are delegatecall-only. Start at the SDK overview.

packages/subgraph — The Graph

Schema + mappings that index InflexionCore events into the queryable history that powers fill attribution and the moat dataset. Deployed and indexing on The Graph Studio — including the three additions (QuoteFilled, SwapPriced, CvammPricing.loadComponents()) — with on-chain history backfilled from the redeploy block. History/aggregate surfaces are served live via the API. See the subgraph integration page.

packages/api — the public REST API

A thin REST service — hosted at https://inflexion-backend.onrender.com (REST API at /, engine at /engine) — over the subgraph, with live-read fallbacks. Reads SUBGRAPH_URL and an RPC from process.env; if SUBGRAPH_URL is unset it degrades to a typed pending state rather than erroring. See the API overview.

apps/web — the dApp

React + Vite, wagmi/viem, RainbowKit, Apollo, shadcn/ui, Recharts. Hosts the Protect, Earn, Underwrite, Markets, and Data surfaces. The market grid mirrors the on-chain marketId derivation exactly — see marketId parity.

apps/docs — these docs

The Mintlify site for docs.inflexion.xyz. Shared disclosures live in snippets/ and are imported, not re-worded — claim-a-disclosure, claim-b-disclosure, maturity-disclaimer, address-table.

quant — the Monte Carlo that gates PARTIAL

Python notebook → the cvAMM parameters (params.cvamm.schema.json). Every PARTIAL parameter and every cvAMM load/skew/σ primitive is produced here, never hardcoded — that is the exact failure the audit flagged. fairRate itself has no calibrated coefficients; only the load stack is calibrated. legacy/ holds the older multi-asset model. See the load stack.

Support directories

Directory	What it holds
docs/	Root-level deep docs: MATH, SECURITY, INTEGRATION, API
scripts/	Cross-platform helpers — .sh and .ps1 for every task
deployments/	Per-network address registries (arbitrum-sepolia.json, …) — the single source of truth the SDK loads

deployments/arbitrum-sepolia.json is the one place an address is allowed to live as a literal. Everything else — SDK, dApp, engine, API — reads from it. That is why these docs never inline an address; they use the shared snippet. See Deployments and Addresses, decimals & units.

Language & version conventions

Conventions are enforced repo-wide; the versions below are pinned.

Solidity

• Version: 0.8.24.
• Compiler: via_ir = true, optimizer at 1M runs (optimizer_runs=1500 was used for the size-constrained 2026-06-05 deploy).
• Format: forge fmt.
• Toolchain: Foundry — forge / cast / anvil, 1.6.0–1.7.0.

TypeScript

• Mode: strict, ES2022, NodeNext.
• Bans: no implicit any, no unchecked indexed access.
• Lint/format: Prettier + ESLint.
• Runtime: node ≥ 20 (24.15.0 installed), pnpm ≥ 9.

Rust (Stylus)

• Edition: 2021, rustc 1.88 pinned.
• Format: cargo fmt.
• Toolchain: cargo-stylus 0.10.x; target wasm32-unknown-unknown.
• Platform: WSL2 / Linux only — see the Stylus note below.
• No floats: Stylus bans WASM floating point at activation, so every transcendental is integer fixed point (1e24 internal, WAD 1e18 ABI).

Python (quant)

• Version: 3.12+ (3.14.5 installed).
• Deps: uv (or poetry); pip works as a fallback.
• Lint: ruff.
• Output: the cvAMM params that gate PARTIAL.

pnpm fmt runs prettier + forge fmt + cargo fmt together; pnpm test runs forge test plus the workspace pnpm -r test. The repo ships a .sh and a .ps1 for cross-platform helpers, so Windows and Unix contributors share one workflow — with one exception, next.

Stylus builds on WSL2 only

The Rust/Stylus crates under packages/contracts/stylus/ — including the production FairValueOracle — build only on WSL2 or Linux, never natively on Windows.

Limit: the Stylus toolchain (rustc 1.88 + cargo-stylus) does not build on native Windows.

Why: the build chain depends on alloy-primitives, which references the Stylus VM hostio native_keccak256 — a symbol only defined at WASM runtime. Linux’s ld tolerates it as an undefined external; Windows MSVC link.exe rejects it (LNK2019 / LNK1120) and breaks the stylus-proc proc-macro DLL build. OffchainLabs patch alloy-primitives / ruint for their own Windows builds but never upstreamed those patches, and the official Stylus Quickstart targets Linux only.

Mitigation: do all Stylus work inside WSL2 Ubuntu 22.04/24.04. The setup is one block — apt deps, rustup default 1.88 + wasm32-unknown-unknown, cargo install --force cargo-stylus. The Solidity stack, SDK, engine, API, web, and quant all build fine on native Windows; only the two Stylus crates need WSL2. The deployed Stylus contract is already live and the SDK only reads it, so day-to-day integration work never touches the Stylus toolchain.

This is a build-environment constraint, not a protocol limitation — the FairValueOracle is deployed and production, and Stylus is why the exact closed-form Φ-sum is affordable on-chain at all (three pillars).

Live state: the subgraph & backend

The subgraph is deployed and indexing on The Graph Studio, and the backend (REST API + Path-B engine) is hosted, so every history / aggregate / time-series surface is live. The structures and queries are mature today; what matures with use is the dataset.

The subgraph is deployed (slug inflexion-arb-sepolia) and has backfilled on-chain history from the redeploy block — the three additions (QuoteFilled, SwapPriced, CvammPricing.loadComponents()) included. The backend is hosted at https://inflexion-backend.onrender.com (REST API at /, engine at /engine), wired to the subgraph, an RPC, and the telemetry sinks; /health reports subgraph:true, live:true. Graceful degradation remains a design property: if a backing (subgraph URL, RPC, telemetry) is absent, surfaces return a typed pending body ('rich-events-absent' / 'no-history-source') rather than erroring. See SDK degradation. On the free hosting tier the backend sleeps after ~15 min idle, so the first request after a lull incurs a cold start.

Limit: the indexed dataset is young — real flow is minimal so far.

Why: the live surfaces (regimes, forward-vol distributions, dispersion) need MM competition (≥ 3 MMs) and volume before their dynamics are statistically meaningful; the structures and queries themselves are live now.

Mitigation: none required — this is expected maturation, not a defect. The schema, mappings, and API contracts are stable; the numbers densify as competition and volume arrive.

See also

Deployments

The live Arbitrum Sepolia address registry — the single source of truth this repo loads.

Decimals & units

dUSDC 6, dWETH 18, feeds 8, WAD 1e18, sqrtPriceX96 Q64.96 — the numéraire conventions.

Environment variables

The .env keys for contracts, engine, API, and the dApp.

Constants

Settlement windows, staleness, lone-spike, and the load/cap constants.