# Simulation methods and limitations

Run with Python 3.8 or newer; only the standard library is required:

```shell
python scripts/bootstrap_simulator.py
python scripts/reward_simulator.py
python -m unittest discover -s scripts -p test_simulators.py -v
```

The generated `reports/bootstrap.md` compares 27 configurations and recommends
one using declared objective weights. Full tick ranges, token allocations,
liquidity, checkpoint inventories, and 1,701 order examples are in JSON and CSV.
`reports/recommended-bootstrap.json` is an analytical recommendation, not an
automatically executable deployment configuration. Integer mint amounts must be
quoted against PoolManager and checked against actual wallet balances.

## Concentrated liquidity math

Let p = human USDG per TOKEN, a/b = lower/upper human prices, and L = human
liquidity. At price clamped to [a,b], TOKEN inventory is
`L * (1/sqrt(p) - 1/sqrt(b))`, and USDG inventory is
`L * (sqrt(p) - sqrt(a))`. Outside the band the position is single sided.
Aggregate all positions to obtain protocol principal balances. Increasing the
price consumes TOKEN and adds USDG. Binary inversion of this monotone reserve
curve determines each order's final price and actual output. A single-range
closed-form test independently checks the inversion.

TOKEN has 18 decimals; simulated USDG has 6. With TOKEN as currency0,
`rawPrice = p * 10^(6-18)`, `tick = log(rawPrice)/log(1.0001)`.
For USDG as currency0 the raw ratio is inverted, and economic upward ranges
have negative/reversed tick orientation. Boundaries are snapped to nearest
spacing-10 ticks in TOKEN0 orientation, then negated/reversed for TOKEN1.
The opening price remains exactly 0.000003 USDG/TOKEN inside the active range.
`rawL = humanL * 10^((18+6)/2)`. Exported raw liquidity is floored.

This uses IEEE double precision, not bit-exact TickMath/SqrtPriceMath. Tiny
rounding/dust differences from Solidity are expected. Raw integers in JSON
must not be parsed as JavaScript Number for deployment. Exact sqrtPriceX96,
Q96 arithmetic, liquidity caps, actual asset decimals, and mint rounding must
be verified by onchain quotation/Foundry tests. No mainnet execution should
consume this file without validation.

The initial active liquidity is solved from the quote budget exactly. If its
TOKEN demand exceeds 65% of the configured inventory, the lower bound is
broadened and snapped downward, then liquidity is solved again. Remaining
TOKEN is spread nonuniformly over adjacent bands with interval-index power
weights. Thus the initial amount of USDG and the TOKEN budget are both conserved.
The final range ends near $2M FDV, leaving measurable depth at $1M. Exhaustion
is a partial execution with unspent quote; the model never invents further depth.

## Optimization and recommendation

Each profile searches 3 lower-bound ratios and 3 allocation powers. The objective
penalizes the worst $100 average impact across the first four checkpoints above its profile tolerance (75%, 40%,
or 25%), rewards $1M depth, and penalizes net capital required to reach $10K FDV.
The cross-profile score independently weighs starting USDG / 500, reserved
TOKEN / 250M, worst early $100 impact above 35%, $1M $1,000 impact above 5%, and
net buying to $10K / 5,000. Lower is better. These are explicit design preferences,
not calibrated investor utility, a global optimizer, or evidence of demand.
Inspect tradeoffs in the report before selecting production parameters.

## Fees, depth, and volume

Gross buy quote is split into 2% reward fee, 0.25% LP fee, and 97.75% reserve
principal as a comparison convention. Both fees use that common executed gross
basis. The model excludes LP fee reinvestment. Actual hook/PoolManager direction,
rounding and settlement semantics must be reconciled with this convention.
Reported average execution impact excludes fees; all-in acquisition premium
includes them. Spot movement is separately reported. Upward 1% depth is net USDG
needed to increase the spot price by 1%; it is not a symmetric sell-depth estimate.

Net buying pressure means net USDG principal added on the one-way path. It is
not trading volume. Repeated buys and sells can generate large volume with little
net movement. The bootstrap model does not simulate that path, arbitrage, MEV,
external LPs, price gaps, repositioning, burns, or market demand. FDV uses the
initial 1B supply consistently; burn-adjusted capitalization requires a separate
supply scenario. The provided curves are initial protocol inventory only.

## Separate reward model

The reward model covers 756 scenarios: seven daily volumes, four participation
rates, nine TOKEN prices, and three alternative reward assets. It subtracts
50 bps of reward capital and $1 per batch by default; CLI flags vary these inputs.
LP fees are separate and are never subtracted from the 2% reward allocation.
Prices per Stock Token unit are illustrative NVDA=150, TSLA=300, AAPL=200 USDG.
They are not live quotations or guaranteed underlying share equivalents.

Reward per $1,000 equivalent TOKEN stake equals net capital times
`1000 / (FDV * stakingParticipation)`. Where this would exceed the entire stake,
the result is null and flagged infeasible. The model assumes static eligible
stakes through the full accounting period / steady-state distribution. It does
not imply that someone staking just before settlement can capture prior fees.
The implementation's streaming and epoch timing affect actual accrual.
The model includes no TOKEN appreciation and does not annualize daily rewards.
Unavailable assets cause delayed settlement; pending USDG is not lost or
implicitly replaced with another asset. Actual ERC-20 units received are the
accounting basis; corporate-action multipliers belong only in economic display.