eigenstate-research

# Eigenstate Research

[![CI](https://github.com/Kaydeep0/eigenstate-research/actions/workflows/ci.yml/badge.svg)](https://github.com/Kaydeep0/eigenstate-research/actions/workflows/ci.yml)
[![Deploy to GitHub Pages](https://github.com/Kaydeep0/eigenstate-research/actions/workflows/deploy.yml/badge.svg)](https://github.com/Kaydeep0/eigenstate-research/actions/workflows/deploy.yml)
[![status: research / pre-revenue](https://img.shields.io/badge/status-research%20%2F%20pre--revenue-informational)](#status-limits-and-non-goals)

[**Site**](https://kaydeep0.github.io/eigenstate-research/) · [**Methodology**](https://kaydeep0.github.io/eigenstate-research/methodology/) · [**Verify walkthrough**](https://kaydeep0.github.io/eigenstate-research/verify-walkthrough/) · [**Ledgers**](#measured-ledgers) · [**Agent index**](https://geniusflow-federation.vercel.app/llms.txt)

Independent measurement of tokenized fixed-income and RWA settlement structure. Observe, measure,
verify, publish. This repo is the public face: reports, dossier mirrors, measured ledgers, MCP
source, and provenance. The runtime engine is private.

**For engineers and analysts who need a claim they can overturn**, not a dashboard they have to
trust. Every published rate has a machine-readable ledger behind it, every refusal names the limb
that failed, and the verifier fails closed on invented attestations.

One command, no install, no account:

```bash
curl -sS -G 'https://geniusflow-federation.vercel.app/api/verify' \
  --data-urlencode 'source_url=https://docs.aave.com/developers/aave-v3/overview' \
  --data-urlencode 'expected=v3'
```

Returns `status: "ATTESTED-PRIMARY"`, `found: true`, `proof_shape.admitted: true`. Change
`expected` to a string the source does not contain and the same endpoint refuses by name. The
difference between those two responses is the whole thesis.

## Contents

1. [Quick start](#quick-start)
2. [What it measures](#what-it-measures)
3. [How it works](#how-it-works)
4. [Measured ledgers](#measured-ledgers)
5. [Public surfaces](#public-surfaces)
6. [Who it is for](#who-it-is-for)
7. [Status, limits, and non-goals](#status-limits-and-non-goals)
8. [Operating this repo](#operating-this-repo)
9. [Documentation and evidence index](#documentation-and-evidence-index)
10. [Contact](#contact)
11. [Appendix A: agent surfaces](#appendix-a-agent-surfaces)
12. [Appendix B: Host operational log](#appendix-b-host-operational-log)

## Quick start

### Admit and refuse in 60 seconds

The command at the top of this file is the admit case. Here is the same endpoint refusing, with
one argument changed:

```bash
curl -sS -G 'https://geniusflow-federation.vercel.app/api/verify' \
  --data-urlencode 'source_url=https://docs.aave.com/developers/aave-v3/overview' \
  --data-urlencode 'expected=not-in-this-page'
```

| Response field | Admit (`expected=v3`) | Refuse (`expected=not-in-this-page`) |
|----------------|-----------------------|--------------------------------------|
| `status` | `ATTESTED-PRIMARY` | `HALLUCINATED` |
| `found` | `true` | `false` |
| `note` | `expected_found_in_source_body` | `expected_not_found_in_source_body` |
| `proof_shape.admitted` | `true` | `false` |
| `proof_shape.failed_limbs` | `[]` | `["refuse_or_admit"]` |
| `proof_shape.refuse_limb` | `null` | `refuse_or_admit` |

Both calls return HTTP 200. The refusal lives in the JSON body, not in the status code, because a
consumer that only checks status codes would read a refusal as a pass. Pipe through `jq` if you
have it.

The full six-step walkthrough (status, dossier, `/api/package` admit, `/api/package` refuse,
grounding verify, return-wire ack) is at
[verify-walkthrough/](https://kaydeep0.github.io/eigenstate-research/verify-walkthrough/).

### Run the demo in 5 minutes

A toy stack, not the private engine. Python 3.8 or newer, no API keys, no accounts.

From a clone of this repo:

```bash
python3 -m venv .venv && . .venv/bin/activate
pip install 'helixhash>=1.0'
python3 public/demo/eigenstate_demo.py
```

Without cloning, in any empty directory:

```bash
python3 -m venv .venv && . .venv/bin/activate
pip install 'helixhash>=1.0'
curl -sO https://kaydeep0.github.io/eigenstate-research/demo/eigenstate_demo.py
python3 eigenstate_demo.py
```

The venv is what makes `pip install` work on a stock macOS or Debian box, where a system-wide
`pip install` is refused as an externally managed environment. Only `helixhash` is needed; the
script uses the standard library for everything else.

**macOS cold start.** If your default `python3` is Homebrew's 3.14, the venv above can die at
`pip` import time before it installs anything. Pin the interpreter instead:

```bash
python3.12 -m venv .venv && source .venv/bin/activate
pip install 'helixhash>=1.0'
python3 public/demo/eigenstate_demo.py
```

The demo itself is fine on 3.12. If you would rather repair the 3.14 toolchain than pin around it,
`brew reinstall expat python@3.14` is the fix.

<details>
<summary>The exact error, if you want to confirm that is what you hit</summary>

On macOS, a Homebrew Python whose `libexpat` has drifted from the interpreter fails at import
time, before any of this code runs:

```
ImportError: dlopen(.../pyexpat.cpython-314-darwin.so): Symbol not found:
_XML_SetAllocTrackerActivationThreshold
```

That is a broken local toolchain, not a problem with the demo. Either pin the venv to a
known-good interpreter, `python3.12 -m venv .venv`, or repair the Homebrew one with
`brew reinstall expat python@3.14`. The demo is verified against CPython 3.12 with `helixhash`
0.1.1 from PyPI.

</details>

**What the demo does.** It reads three public series (FRED SOFR, DeFiLlama BUIDL TVL, GitHub
stars), measures each as `delta_I = |log2(current / prior)|`, crosses them into a local HelixHash
chain, then tampers with one entry in-process so you watch `verify()` flip to `False` and back. It
ends on the latest Base commit in the bundled index. If a source is unreachable the run still
completes on pinned fallback values and labels each observation as live or fallback. The demo is
not production cadence, full topology coverage, or continuous on-chain commits.

HelixHash is the underlying primitive and is separately published:
[Kaydeep0/helixhash](https://github.com/Kaydeep0/helixhash) · [HELIXHASH.md](HELIXHASH.md).

## What it measures

Tokenized funds, stablecoin rails, and on-chain settlement look transparent at the surface. The
hard parts stay opaque: who can settle, under what clock, against which benchmark, with what
custody and regulatory path.

Markets price the product. Few parties systematically measure the **structure underneath**: the
obligations, permissions, and dependencies that decide whether settlement actually works.
Eigenstate is a research measurement stack for that structure. It does **not** predict prices or
trade markets.

| Step | What happens |
|------|--------------|
| **Observe** | Watch a fixed map of institutions and rails that matter for tokenized fixed income |
| **Measure** | Score how much *new* information each entity produces relative to watch cost |
| **Verify** | Fact-check and admit or refuse claims before they are treated as published |
| **Publish** | Ship human reports on Pages; commit attestations on Base when gates allow |

```mermaid
flowchart LR
  T[Topology] --> S[Sensors / Parkash]
  S --> V[Vault<br/>hash chain]
  V --> VER[VERIFY / proof_shape]
  VER --> P[Pages report]
  VER -.->|when gates allow| B[Base commit]
```

Base attestation is gated, not per cycle. Depth and caveats: [Methodology](https://kaydeep0.github.io/eigenstate-research/methodology/) ([md](METHODOLOGY.md)).

### E = ΔI / A

Information efficiency: new information gained (**ΔI**) over observation cost (**A**). A
structural metric, not a forecast.

*Example.* On an SEC filing day, a new rulemaking document against the prior expected state gives
high **E**. The same feed on a quiet day gives low **E**.

## How it works

Four mechanisms, each with a public artifact you can open.

### Vault

Qualifying observations append to a hash-chained measurement log (ΔI / E plus integrity fields).
Entity field numbers **Φ_S** and **κ** (not **Γ**) are mirrored on public dossiers. Changing an
old vault row breaks later hashes and parent checks.

*Example.* After a qualifying read of CIRCLE or BLACKROCK, the private vault appends a chained
row and the dossiers expose live Φ_S / κ. Public mirrors:
[CIRCLE](https://kaydeep0.github.io/eigenstate-research/federation/dossier/CIRCLE.json) ·
[BLACKROCK](https://kaydeep0.github.io/eigenstate-research/federation/dossier/BLACKROCK.json).
Not every vault row becomes a report.

### Helix commit and on-chain attestation

Local chaining is continuous. On-chain commits to `GeniusFlowSettlement` on Base land when
wallet, balance, and mirror gates pass. Attested when it lands, not every cycle.

*Example.* Historical commits:
[On-Chain Proof Index](https://kaydeep0.github.io/eigenstate-research/onchain/) (machine readable:
[`/api/onchain.json`](https://kaydeep0.github.io/eigenstate-research/api/onchain.json)). Sample
tx: [0x5a132a48…77a66](https://basescan.org/tx/0x5a132a48097c67063afcee39f3d06ee3f35166570b4eefcc18eefaa54d877a66).
Prefer the index over any single hard-coded hash.

### Verification rails

Dispatch fact-check, then VERIFY / `status_at_publish`, then federation proof_shape admit or
refuse. Cheap copies that invent "attested" labels fail.

*Example.* A package with a real registry reference and a provenance spine can **admit**. One
that stamps ATTESTED without that spine **refuses**. Spec:
[ATTESTATION_PROOF_SHAPE.md](https://geniusflow-federation.vercel.app/docs/ATTESTATION_PROOF_SHAPE.md).

### Structural gap detection

We look for what the topology *needs* that product design still treats as optional.

*Example.* SOFR plus ISDA fallback is often treated as a full LIBOR replacement. The stack still
scores a persistent term-structure gap (`LIBOR_EQUIVALENT`). See
[predictions/]