Documentation — quantumOS

01 · Status

What exists, honestly.

Landing, simulator, rule builder, math labImplemented — runs in the browser
Economic math library + unit testsImplemented — 24 tests, every example on this page is computed from it
Token onboarding UIPrototype — address format check only; chain reads need RPC
Quantum-inspired optimizerResearch — classical CPU only
Wallet, indexer, contracts, AI providerNot implemented — to be integrated
Quantum hardware / QAOARoadmap

02 · Architecture

Authorized in. Verified rules. Bounded out.

Funds flow left to right. Policy and risk sit above and below the vault and must both agree before the router moves anything. Click a node.

Simulate route tosimulation only — nothing is sent on-chain

01

AI proposes

Off-chain analysis produces a typed policy proposal. It never signs and never emits executable code.

02

Code validates

Deterministic checks (limits, freshness, slippage, reserve) accept or reject. Same logic off-chain and on-chain.

03

Contracts execute

Only allow-listed adapters, only bounded recipients, only within caps. Everything else reverts.

03 · Revenue & budgets

From volume to a budget you can spend.

Three steps: estimate captured revenue, subtract real costs, split the remainder by weights that must sum to exactly 100%.

Gross captured revenue

R_{gross}=V\cdot\tau\cdot c

Capture

c

is the share of fees that actually reach the vault. It is zero unless the token, pool or owner is wired to send fees there.

Symbol	Meaning	Unit
$V$	Eligible daily trading volume	USD/day
$\tau$	Applicable fee rate	fraction
$c$	Fraction captured by the platform, 0 ≤ c ≤ 1	fraction
$R_{gross}$	Gross captured revenue	USD/day

Net distributable budget

R_{net}=\max\!\big(0,\;R_{gross}-C_{exec}-C_{protocol}-C_{other}\big),\qquad \text{deficit}=\max(0,\;C-R_{gross})

If costs exceed revenue the budget is zero and the shortfall is reported separately — never as a negative budget.

Allocation

B_i=R_{net}\,a_i,\qquad a_i\ge 0,\qquad \sum_{i=1}^{n}a_i=1

Weights are integer basis points. An invalid total is rejected, not silently rebalanced. Rounding uses the largest-remainder method in micro-USD so shares always add back to the budget exactly.

Worked example

R_gross = 1,000,000 × 0.02 × 0.75 = $15,000.00/day
R_net = $15,000.00 − $120 gas − $60 platform = $14,820.00
Buyback 30% = $4,446.00 · Liquidity 25% = $3,705.00
Treasury 35% = $5,187.00 · Rewards 10% = $1,482.00
Σ = $14,820.00 · residual = 0 µUSD

Limitation

This is accounting arithmetic, not an assertion that a DEX pays fees to the protocol. Actual revenue must be observed from balances.

04 · Reserve floor

Spending is bounded by what stays behind.

Basic reserve constraint

T-S\ge T_{min}\quad\Longleftrightarrow\quad S\le T-T_{min}

Worked example

T = $120,000 · T_min = $50,000
S_max = 120,000 − 50,000 = $70,000
Proposed buyback $4,446 + rewards $1,482 + liquidity $3,705 = $9,633 → allowed

Limitation

This is the single-asset simplification. A real floor must value assets in different denominations, account for liquidity and pricing uncertainty and include liabilities. Prices must come from fresh, bounded oracles.

05 · AMM swaps

Derive it once, trust it forever.

For a constant-product pool the swap output follows from one invariant. The fee is taken off the input first and stays in the pool.

Invariant

x\cdot y=k

Derivation

\begin{aligned}(x+\Delta x_{eff})(y-\Delta y)&=x\,y\\ y-\Delta y&=\frac{x\,y}{x+\Delta x_{eff}}\\ \Delta y&=y-\frac{x\,y}{x+\Delta x_{eff}}=\frac{y\,\Delta x_{eff}}{x+\Delta x_{eff}},\qquad \Delta x_{eff}=\Delta x(1-f)\end{aligned}

Symbol	Meaning	Unit
$x$	Quote-asset reserve	ETH
$y$	Token reserve	tokens
$\Delta x$	Quote amount paid in	ETH
$f$	Effective LP fee	fraction
$\Delta y$	Tokens received	tokens

x = 100 ETH, y = 1,000,000 tokens, Δx = 50 ETH, f = 0.3% (a large trade, so the gap is visible). The dashed tangent is the starting spot price; the solid chord is what the trade actually paid on average. The gap between them is price impact.

Spot vs execution price

P_{spot}=\frac{x}{y},\qquad P_{exec}=\frac{\Delta x}{\Delta y}

Two different numbers, kept apart

\text{impact}_{ex\text{-}fee}=\frac{\Delta x_{eff}/\Delta y}{x/y}-1=\frac{\Delta x_{eff}}{x},\qquad \text{impact}_{total}=\frac{P_{exec}}{P_{spot}}-1=\frac{1+\Delta x_{eff}/x}{1-f}-1

The ex-fee form is exact: the price moved by the trade itself is just the effective input divided by the reserve. The LP fee is a separate, deliberate cost.

1 ETH into the pool

Δx_eff = 0.997 ETH
Δy = 1,000,000 × 0.997 / 100.997 = 9,871.58
impact ex-fee = 0.997%
impact total = 1.301%

20 ETH into the pool

Δx_eff = 19.94 ETH
Δy = 166,249.79 tokens
impact ex-fee = 19.940% (= 19.94/100)
impact total = 20.301%

Limitation

Valid only for constant-product pools. The ex-fee impact is exactly linear in trade size (20× the ETH gives 20× the impact), but the tokens received grow sublinearly: 20× the ETH bought only 16.8× the tokens, because every unit is bought at a worse price than the last.

06 · V3 / V4 limits

Why V2 math is not V3 math.

Concentrated liquidity uses ticks and a liquidity value L. The x·y = k formulas above are not an approximation of it.

V3 price and virtual reserves (token0 = x, token1 = y, price P = y/x)

P=1.0001^{\,\text{tick}}=\Big(\frac{\text{sqrtPriceX96}}{2^{96}}\Big)^{2},\qquad L=\sqrt{xy},\;\; x=\frac{L}{\sqrt P},\;\; y=L\sqrt P

Swap inside one tick range

\Delta\sqrt P=\frac{\Delta y}{L},\qquad \Delta\!\Big(\frac{1}{\sqrt P}\Big)=\frac{\Delta x}{L}

Crossing a tick changes L, so exact execution must walk ticks. quantumOS does not approximate this with the V2 formula.

V3 oracle: time-weighted tick, then geometric-mean price

\overline{\text{tick}}=\frac{\text{tickCumulative}_b-\text{tickCumulative}_a}{t_b-t_a},\qquad \mathrm{TWAP}_{V3}=1.0001^{\,\overline{\text{tick}}}

This is a geometric mean of price over the window. The arithmetic TWAP used elsewhere on this page is a different quantity; they are not interchangeable.

Risk

Uniswap V4 hooks are attached to a pool at initialization and cannot be added to an existing pool. A dynamic LP fee is not a token transfer tax, and hook-managed fees are not automatically revenue owned by this platform.

07 · Volatility & TWAP

Measure the past. Never promise the future.

Log returns

r_t=\ln\frac{P_t}{P_{t-1}}

Log returns add across time:

\sum_t r_t=\ln(P_T/P_0)

.

Sample volatility, annualised

s_r=\sqrt{\frac{1}{N-1}\sum_{t=1}^{N}(r_t-\bar r)^2},\qquad \sigma_{ann}=s_r\sqrt{A}

A

is the number of sampling intervals per year and must match the real interval: 365 for daily 24/7 sampling by convention, 8760 for hourly. The √A scaling assumes independent returns, which real markets violate.

Time-weighted average price (arithmetic)

\mathrm{TWAP}=\frac{\sum_i P_i\,\Delta t_i}{\sum_i \Delta t_i}

Volatility

P = 100, 102, 101, 105, 103, 108, 104
r = 1.98%, -0.99%, 3.88%, -1.92%, 4.74%, -3.77%
s_r = 3.401% per day
σ_ann = 3.401% × √365 = 65.0%

TWAP

P = 10 for 1h, then 20 for 3h
TWAP = (10·1 + 20·3) / 4 = 17.5
Plain average would be 15

Risk

Oracle use needs stale-data checks, a minimum observation window, a liquidity floor and a defined failure mode. A TWAP over a thin pool can still be manipulated.

08 · Monte Carlo

Not one future. Eight hundred.

The twin simulates the treasury path many times under stated assumptions and reports the spread, including the bad tail.

Volume model (mean-corrected log-normal)

\ln V_t=\mu+\sigma Z_t,\;\; Z_t\sim\mathcal N(0,1),\;\; \mu=\ln\bar V-\tfrac{\sigma^2}{2}\;\Rightarrow\;\mathbb E[V_t]=\bar V

Treasury recursion

T_t=T_{t-1}+\rho\,R^{net}_t-\text{deficit}_t,\qquad R^{net}_t=\max(0,V_t\tau c-C),\;\;\text{deficit}_t=\max(0,C-V_t\tau c)

\rho

is the share of the net budget retained in the treasury. A liquidity shock multiplies

V_t

by

(1-\text{cut})

with a small daily probability.

Outputs

q_p=s_{(\,(N-1)p\,)},\quad \Pr[\text{breach}]\approx\frac1N\sum_{k=1}^{N}\mathbf 1\!\big[\min_t T^{(k)}_t<T_{min}\big],\quad \mathrm{SE}=\sqrt{\tfrac{\hat p(1-\hat p)}{N}}

Quantiles are empirical (linear interpolation on the sorted sample). With N = 800 paths a probability near 10% carries a standard error of about 1.1 percentage points — the simulation is a stress test, not a forecast.

P5 end

$181,241

Median end

$211,041

P95 end

$249,343

Floor breach

0.0%

V̄ = $400k/day, σ = 80%, τ = 2%, c = 70%, costs $1,000/day, T₀ = $80k, floor $50k, ρ = 50%, 60 days, shock p = 4%/day (−70% volume), seed 5. Re-runs are bit-identical for the same seed.

Assumption

Volume is independent day to day, has constant σ and no regime change. Real volume is autocorrelated and fat-tailed, so tails here are probably optimistic.

09 · Optimization & QUBO

From allocation to a binary problem.

Start with a trustworthy classical baseline. Then encode the same problem as a QUBO to study annealing — and validate every answer.

Risk-adjusted objective

\max_a\;\;U(a)-\lambda R(a)-\mu C(a),\quad U=\sum_i g_i a_i-\tfrac12\sum_i d_i a_i^2,\;\; R=\sum_i\rho_i a_i^2,\;\; C=\sum_i\kappa_i a_i

s.t.

\sum a_i=1,\; 0\le a_i\le \mathrm{cap}_i,\; a_{treasury}\ge \text{floor}

. All terms are dimensionless scores. The coefficients are user choices, not empirically validated values.

Binary encoding

a_i\approx\frac{\sum_{k=0}^{K-1}2^{k}z_{i,k}}{M},\qquad M=2^K-1,\;\; z_{i,k}\in\{0,1\}

K bits give a resolution of 1/M. K = 4 means weights move in steps of 6.67%.

Energy with penalties

E(z)=-\text{obj}(a(z))+P_{sum}\Big(\sum_i a_i-1\Big)^2+P_{cap}\sum_i\max(0,a_i-\mathrm{cap}_i)^2

Only the budget term is genuinely quadratic in z. The cap and floor terms are hinges; a strict QUBO would need slack bits. Penalties do not guarantee a feasible result.

The budget penalty as a QUBO matrix (z² = z)

P\Big(\sum_p c_p z_p-1\Big)^2=\sum_p P(c_p^2-2c_p)\,z_p+\sum_{p<q}2P\,c_pc_q\,z_pz_q+P,\qquad c_p=\tfrac{2^k}{M}

Computed Q for 2 variables × 2 bits (K = 2, M = 3, P = 1) · constant = 1

bit	z0	z1	z2	z3
z0 · c = 0.333	-0.556	0.444	0.222	0.444
z1 · c = 0.667	·	-0.889	0.444	0.889
z2 · c = 0.333	·	·	-0.556	0.444
z3 · c = 0.667	·	·	·	-0.889

Verified in unit tests: the matrix reproduces P(Σa − 1)² for all 16 bit patterns, and gives exactly 0 on budget-feasible ones (e.g. z = 1001 → 1/3 + 2/3 = 1).

Try it — grid search vs annealing

\max_a; U(a)-\lambda R(a)-\mu C(a),\quad U=\textstyle\sum g_i a_i-\tfrac12\sum d_i a_i^2,; R=\sum \rho_i a_i^2,; C=\sum \kappa_i a_i

a_i=\frac{\sum_{k=0}^{K-1}2^k z_{i,k}}{2^K-1},\quad E(z)=-\text{obj}(a)+P(\textstyle\sum_i a_i-1)^2+\text{hinge penalties}

Coefficients g, d, ρ, κ are illustrative and chosen by the user. They are not empirically validated.

λ (risk)

μ (cost)

Treasury floor share

SA seed

Bits / variable K

Risk

Quantum-inspired here means classical simulated annealing on a QUBO encoding. QAOA and real quantum hardware are not implemented, and no quantum advantage is claimed. Solver output must pass deterministic feasibility validation before it can influence any policy.

10 · Rewards

Split fairly. Lose nothing.

Rewards are distributed by snapshot weights. Integer division leaves a few base units; they are accounted for explicitly.

Proportional share

\text{Reward}_j=\Big\lfloor\frac{R\,w_j}{W}\Big\rfloor,\qquad W=\sum_j w_j>0,\qquad \text{residual}=R-\sum_j\text{Reward}_j

Worked example

R = 100 units, weights 1 : 1 : 1
shares = [33, 33, 33] · residual = 1
The residual stays in the distributor and is carried to the next epoch

Claim-based distribution (why not loop over holders)

\text{leaf}_j=\operatorname{keccak256}\big(j\,\Vert\,a_j\,\Vert\,r_j\big),\qquad \text{verify}(\pi_j,\text{root},\text{leaf}_j)\;\wedge\;\neg\text{claimed}[j]

Enumerating holders on-chain is impractical, so a snapshot is committed as a Merkle root and holders claim with a proof. A claimed-bitmap prevents double claims, and the total funded must cover Σ r_j. Use a standard, audited tree implementation to avoid second-preimage pitfalls.

11 · Gas

Wei, exactly.

Gas costs are computed with arbitrary-precision integers. A floating-point number must never touch token accounting.

Execution cost (EIP-1559 style)

\text{effectiveGasPrice}=\min\big(\text{maxFee},\;\text{baseFee}+\text{priorityFee}\big),\qquad \text{cost}_{wei}=\text{GasUsed}\times\text{effectiveGasPrice}

Conversion

\text{cost}_{native}=\frac{\text{cost}_{wei}}{10^{18}},\qquad \text{cost}_{USD}=\text{cost}_{native}\times P_{native/USD}

Worked example

GasUsed = 185,000 · price = 0.08 gwei = 80,000,000 wei
cost = 14800000000000 wei = 0.0000148 ETH
At $3,000/ETH ≈ $0.0444

Layer-2 chains

\text{fee}_{L2}=\text{fee}_{execution}+\text{fee}_{L1\,data}

On Base and Arbitrum the L1 data component can dominate. The calculator in this preview does not include it, and says so.

12 · Guardrails

Every limit, as an inequality.

Reserve floor

T-S\ge T_{min}

Daily cap

\sum_{24h}S_i+S\le \text{Cap}_{day}

Slippage bound

\text{minOut}\ge Q_{TWAP}\,(1-s_{max})

Oracle deviation

\frac{|P_{spot}-\mathrm{TWAP}|}{\mathrm{TWAP}}\le\delta

Oracle freshness

t_{now}-t_{update}\le \Delta_{max}

Observation window

N_{obs}\ge N_{min}

Assumption

These are design targets for the on-chain RiskController. The same checks run today in the browser (see the Security Guardian), but no contract enforces them yet.

13 · AI & quantum honesty

What the models may and may not do.

May

Summarise measured signals (returns, volatility, depth)
Propose a policy in a typed schema
Explain a warning in plain language
Run what-if scenarios in the twin

May not

Sign transactions or hold keys
Emit and deploy executable Solidity
Claim to predict price or identify bot owners
Override a deterministic validator

Limitation

No language-model provider is connected in this preview. The Policy Composer shows its disabled state instead of fabricated output.

14 · Chains & DEXs

Same EVM, different realities.

Type	Math	Caveat	Status
Uniswap V2-type	x·y = k reserves	Fee-on-transfer tokens need a router and token tested together	Planned first adapter
Uniswap V3-type	Ticks and liquidity L	Fee-on-transfer tokens are not generally compatible with standard routers	Not implemented
Uniswap V4	Hooks, custom accounting, dynamic LP fees	Hook is bound at pool initialization; LP fee ≠ token tax; hook fees are not automatically platform revenue	Research

Chain	ID	Native	Type	Notes
Ethereum	1	ETH	L1	Highest gas cost; deepest liquidity. EIP-1559 fee market.
Base	8453	ETH	L2	L2: total fee = L2 execution + L1 data fee.
BNB Smart Chain	56	BNB	L1	Native asset is BNB. Different finality and infrastructure from Ethereum.
Arbitrum One	42161	ETH	L2	L2 with its own gas accounting that includes an L1 component.

No protocol contract addresses are listed: none have been verified against official sources yet.

15 · Limits & checklist

Known limits. Required before production.

No on-chain reads, wallet or contracts yet; every on-chain panel shows an honest unavailable state.
Prices, gas and volatility inputs are manual or synthetic; no live feed is connected.
Simulations are only as good as their assumptions and do not predict returns.
The optimizer uses illustrative coefficients; it is not empirically validated and uses no quantum hardware.
USD figures in the UI model are floating point for display; token accounting in contracts must use integers.

Production readiness

Independent smart-contract audit published
Contracts verified on every target chain
Timelock and role tables reviewed
Invariant and fork tests green
Chain-specific fee accounting (L1 data fee) implemented
Oracle/TWAP sources documented per pool type
Incident and pause runbook written
Legal and regulatory review

Environment template

NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=
RPC_URL_1=
RPC_URL_8453=
RPC_URL_56=
RPC_URL_42161=
ANTHROPIC_API_KEY=           # server-side only, for the policy composer
DATABASE_URL=                # indexed data (server-side)