Futarchy was invented by Prof. Robin Hanson — thank you for your work; this project exists to build one.
Bleavit is a futarchy-governed Polkadot parachain. Token holders vote on values — what the chain should optimize. Conditional prediction markets decide beliefs — which proposals actually reach execution. Every consensus-critical rule is a native Rust FRAME pallet, so no smart-contract environment enters the trusted computing base.
Important
Bleavit is not deployed. The Phase 0 and Phase 1 exit gates passed. Phase 2
puts the chain on the Paseo testnet, and that gate is still open. Do not commit
real funds to any part of this repository.
docs/reviews/ holds the review reports the project has
received so far.
- What Bleavit is
- How it works
- Project status
- Quick start
- Documentation
- Repository map
- Development
- Contributing
- Security
- License
Ordinary governance mixes two questions into one vote. Bleavit separates them into two layers, and gives each layer a mechanism suited to it.
- Values — what should we want? VIT holders vote through
pallet-referendaandpallet-conviction-voting. This layer defines the welfare metric and its weights. It can never enact an operational proposal. - Beliefs — what will actually work? Conditional prediction markets price each proposal against the world without it. A proposal executes only when its markets say it raises the welfare score, and only when no ruin gate vetoes it.
The canonical client matches that posture. It is a static app distributed over Arweave, and it runs an in-browser light client. It has no backend, no indexer dependency, and no telemetry.
Each mechanism below has one owning specification document. Follow the link for the normative detail.
- Scalar Mode B futarchy over a normalized welfare score — 05
- An LMSR market maker in verified 64.64 fixed point — 04
- A purpose-built conditional ledger with machine-checked solvency invariants — 03
- A bonded optimistic oracle with escalating disputes and a hard latency cap — 07
- An execution guard with narrow class-specific origins, never unrestricted Root — 09
- A hosted question service that other chains call over XCM — 16
- An eight-phase rollout that removes
pallet-sudoat Phase 4 — 09
Two rules shape the whole repository. Every observable behavior traces to a specification section. Every parameter value lives in exactly two documents — 02 for the contract surface, and 13 for everything else.
The specification is complete. The chain is not deployed.
PLAN.md and the plan/ tree are the single source of
implementation status, and they win over the summary below.
| Track | What it covers | Status |
|---|---|---|
| M — Foundations | Cargo workspace, shared primitives, 64.64 fixed point, reference model | ✅ Done |
| A — Protocol pallets | Ledger, markets, welfare, oracle, guardians, treasury, execution guard | ✅ Done |
| N — External clients | The hosted question service other chains call over XCM | ✅ Done |
| B — Runtime, node and chain | Cumulus runtime, collator, XCM layer, release pipeline, keeper | 🔨 Mostly done |
| E — Revenue and sustainability | Redemption fee and the self-funding statement | 🔨 Mostly done |
| S — Verification and simulation | TLA⁺ models, fuzz targets, property suites, economic simulation | 🔨 Mostly done |
| F — Canonical client | The Arweave-distributed app in app/ and its light client |
🔨 In progress |
| O — Release and operations | Runbooks, monitoring, bootnode operations | 🔨 In progress |
| G — Rollout gates | Eight evidence-gated phases, from local drills to a self-governing chain | 🔨 Phase 2 next |
The specification came from an adversarial design review, and it resolves all 101 findings that review raised. Treat changes to it as rare and deliberate. It is editable rather than guarded — see rule R-1 in AGENTS.md.
| Tool | Version | Where the pin lives |
|---|---|---|
| Rust | 1.89.0, with the two wasm targets | rust-toolchain.toml — rustup reads it for you |
| Node.js | 22.19.0 | app/.nvmrc |
| pnpm | 10.23.0, through corepack | packageManager in app/package.json |
| Python | 3.12 | .github/workflows/ci.yml |
The Rust build needs two native packages. On Debian or Ubuntu, install them with
sudo apt-get install -y libclang-dev protobuf-compiler.
This path needs no installation. Start at
docs/architecture/README.md. Then read
01 → 02 → 03 → 04 → 05 in that order.
The explainer animates every mechanism in fourteen scenes. It reads no chain, so it starts in seconds.
npm -C explainer install
npm -C explainer run devThis path builds the collator and boots a relay chain beside it. Expect a long first build.
tools/env/fetch-binaries.sh
tools/env/generate-relay-specs.sh
cargo build --release -p bleavit-node --locked
(cd keeper && cargo build --release --locked -p bleavit-keeper)
zombienet/bin/zombienet -p native spawn zombienet/networks/bleavit-local.tomlzombienet/README.md documents the drills, the fast-timing
test spec, and the host requirements. The fetch script verifies every download,
then installs it. tools/env/pins.env is the one home for
those pins.
(cd app && corepack enable && corepack install)
pnpm -C app install --frozen-lockfile
pnpm -C app dev| If you want to | Start here |
|---|---|
| Understand the protocol | docs/architecture/ — 16 component documents plus the decision record |
| Watch the protocol move | explainer/ — an interactive teaching site, not the canonical client |
| Integrate a client | docs/integration/ — plain language, non-normative, nine guides |
| Know what is built | PLAN.md for current focus and plan/ for per-item status, generated indexes and dated history |
| Contribute code | AGENTS.md — the rules, the quality gates, the session loop |
| Operate a node | deploy/runbooks/ and deploy/monitoring/ |
| Design a frontend | docs/design/ — a derived, non-normative design kit |
| Report a vulnerability | SECURITY.md |
| Path | What it is |
|---|---|
docs/architecture/ |
The specification, and the source of truth for every behavior |
docs/integration/ |
Human-facing guides for people who integrate a client |
PLAN.md, plan/, AGENTS.md, CLAUDE.md |
Current focus, detailed status, the operating manual, and the Claude Code wiring |
crates/ |
Shared primitives, the fixed-point kernel, and frame-free no_std functional cores |
pallets/ |
Production FRAME pallets, mostly thin shells over those functional cores |
runtime/, runtime-api/, node/ |
The Cumulus runtime, the frozen FutarchyApi, and the collator binary |
app/ |
The canonical client, and the TypeScript port of the market math |
explainer/ |
The interactive teaching site — no signing affordance, no chain reads |
reference-model/, simulation/ |
An independent executable specification in Python, plus the economic simulation |
models/, fuzz/ |
TLA⁺ formal models and the invariant fuzz targets |
keeper/ |
The off-chain keeper that cranks permissionless lifecycle extrinsics |
deploy/, zombienet/, chopsticks/ |
Chain specs, runbooks, monitoring, and the test environments |
tools/ |
CI gate tooling and the release pipeline |
SIGNERS.md |
The signer registry, whose populations print as unseated until the key ceremony |
AGENTS.md · Repository layout carries the long-form version of this table, one row per path.
- Runtime: Rust and the Polkadot SDK on release line
polkadot-stable2606, with FRAME and Cumulus. Verification uses Zombienet, Chopsticks, try-runtime, TLA⁺ and cargo-fuzz. - Client: TypeScript, polkadot-api 2.x, smoldot 3.x, Vite 8 and Dexie 4. Arweave distribution runs through permaweb-deploy and Turbo.
- Reference model: Python high-precision arithmetic, a regenerated vector corpus, and a release-gated differential sweep of at least 10⁷ points.
Run the changed-scope Rust gate while you work. It locks the dependency graph and skips what your change cannot reach.
tools/ci/rust-workspace-gates.sh --changed <package>The same script with no argument runs the exhaustive gate. That run takes hours on a cold machine, so let CI carry it. The other suites each own one area:
pnpm -C app install --frozen-lockfile && pnpm -C app test
npm -C explainer run verify
PYTHONPATH=reference-model/src python3 -m unittest discover -s reference-model/testsAGENTS.md · Quality gates lists every gate with the specification section that mandates it.
Coding agents build the project one plan/ milestone at a time, under
three standing constraints:
- Every observable behavior traces to a specification section (rule R-1).
- Parameter values come only from document 13, or from the contract surface in document 02.
- The living documents stay true in the same session as any change (rule R-3).
Humans and agents alike: read AGENTS.md, then PLAN.md and its linked plan items, then work.
This repository has no separate contributing guide, because AGENTS.md is that guide for humans and agents alike. Read it first. Then read PLAN.md and its linked plan items for the current focus.
Three things matter more here than in most repositories:
- Read the owning specification section before you write code. Never guess a parameter value, a name, or a semantic.
- Never mark work done with a failing gate. Report the failure verbatim instead.
- Use conventional commits with the milestone id, as in
feat(ledger): split/merge families with per-branch supplies (A2).
Report vulnerabilities through GitHub's private reporting feature, and never
through a public issue or pull request. SECURITY.md gives the
full process and the response times.
Bleavit is financial infrastructure. Solvency-critical code carries adversarial tests. It rounds against the claimant, and it defaults to the status quo on every failure path.
You theorized it, we are cooking it. Bon appétit, Prof. Hanson.