research/tools/simulators/tsi/tsi-sim/README.md

tsi-sim — Cryptarchia Total Stake Inference simulator (uncle references)

Monte-Carlo simulation framework used to choose safe values for the uncle-reference parameters of Cryptarchia's Total Stake Inference (TSI):

• U — max uncles referenced per block (MAX_UNCLES); U=0 is the no-uncle baseline.
• W — uncle reference window in slots (spec default 300).
• swept against network size N, stake distribution S (uniform / Pareto), and network latency L (in slots — deliberately not D, which denotes the stake estimate).

It measures how well the inferred total active stake D tracks the true total stake, and whether uncle references recover the active slots that network latency loses to forks.

This lives under a raw/ docs path, so it is invisible to the repository's markdown-lint CI. It is a standalone Python package with its own tooling.

Model

Reduced canonical-chain-with-orphans model: we simulate the global winning-slot sequence (stake-weighted φ lottery), build a real block tree with latency- and multi-winner-induced forks, resolve the canonical chain (honest longest-chain), let canonical blocks reference uncles per the spec's selection rules, and count TSI density m = honest-chain blocks + deduplicated referenced uncles in the measurement window. All honest nodes converge to the same deep chain (k-finality), so a single per-epoch D is faithful. A full per-node model is the planned next phase (per_node_dest flag scaffolds it).

See the sibling spec ../ and ../../cryptarchia-total-stake-inference.md for the math.

Quick start

make install         # create .venv and install (editable) with dev deps
make test            # unit tests + fast theory checks
make verify          # simulator vs closed-form analytic checks
make smoke           # tiny scaled-k sweep + figures (end-to-end smoke test)
make sweep figures   # full scaled-k parameter sweep + academic figures

Outputs: results/*.parquet (one row per config×epoch) and figures/*.{pdf,png} (both git-ignored).

Scale

True constants (k=2160, f=1/30) give 648,000-slot epochs — too large to sweep. Mean accuracy is provably k-invariant (only variance scales ~1/T), so sweeps use a scaled k (configs/default.yaml); the final accuracy/variance figures re-run at true k (configs/fullscale.yaml). configs/smoke.yaml is a tiny dev grid.

Layout

src/tsi_sim/   constants config rng stake lottery latency blocktree uncles
               tsi epoch engine metrics theory sweep  plotting/{style,figures}
scripts/       run_sweep.py  make_figures.py  verify.py
configs/       smoke.yaml  default.yaml  fullscale.yaml
tests/         test_{lottery,uncles,tsi_counting,blocktree,theory_convergence}.py