Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 7 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Bulkhead is a small Solana program that holds a protocol's token accounts on the

**[The attack](#what-it-does-to-an-attack)** · **[How it works](#how-it-works)** · **[Verify it](#verify-it-yourself)** · **[Devnet](#live-on-devnet)** · **[FAQ](docs/FAQ.md)** · **[Docs](#documentation)**

[![CI](https://github.com/shuv-amp/bulkhead/actions/workflows/ci.yml/badge.svg)](https://github.com/shuv-amp/bulkhead/actions/workflows/ci.yml) [![devnet](https://img.shields.io/badge/devnet-live-57606A?style=flat-square)](#live-on-devnet) [![Kani](https://img.shields.io/badge/Kani_proofs-15%2F15-57606A?style=flat-square)](docs/09-VERIFICATION.md) [![tests](https://img.shields.io/badge/program_tests-123%2F123-57606A?style=flat-square)](docs/09-VERIFICATION.md) [![audit](https://img.shields.io/badge/audit-not_yet,_not_for_real_funds-E5481B?style=flat-square)](SECURITY.md) [![license](https://img.shields.io/badge/license-Apache--2.0-57606A?style=flat-square)](LICENSE)
[![CI](https://github.com/shuv-amp/bulkhead/actions/workflows/ci.yml/badge.svg)](https://github.com/shuv-amp/bulkhead/actions/workflows/ci.yml) [![devnet](https://img.shields.io/badge/devnet-live-57606A?style=flat-square)](#live-on-devnet) [![Kani](https://img.shields.io/badge/Kani_proofs-17%2F17-57606A?style=flat-square)](docs/09-VERIFICATION.md) [![tests](https://img.shields.io/badge/program_tests-133%2F133-57606A?style=flat-square)](docs/09-VERIFICATION.md) [![audit](https://img.shields.io/badge/audit-not_yet,_not_for_real_funds-E5481B?style=flat-square)](SECURITY.md) [![license](https://img.shields.io/badge/license-Apache--2.0-57606A?style=flat-square)](LICENSE)

<br>

Expand Down Expand Up @@ -144,7 +144,7 @@ scripts/check-programs.sh # the programs on the real runtime: needs the
E2E=1 scripts/check-programs.sh # ...plus the attacker-vs-guardian run and a deploy rehearsal, on local validators
scripts/prove.sh # Kani bounded proofs (~6 min)
scripts/mutants.sh # mutation testing (~45 min)
scripts/fuzz.sh # coverage-guided fuzzing, 8 targets (SECONDS_PER=600 for longer)
scripts/fuzz.sh # coverage-guided fuzzing, 9 targets (SECONDS_PER=600 for longer)
scripts/deny.sh # supply chain: RustSec advisories, licences, crate sources
python3 tools/floor_check.py <program-id> # who can upgrade any mainnet program; is it ready for SIMD-0500? (--rpc <url> for another cluster)
scripts/floor-demo.sh <program-id> # Floor on that program's real bytes, locally: register, stop, restore byte-identical
Expand All @@ -165,12 +165,12 @@ These scripts install nothing. The core has zero dependencies, and Cloud and the

| Check | Result (latest run of each) |
|---|---|
| **Programs on the real runtime** <br><sub>LiteSVM, mainnet feature set, mainnet token program</sub> | **123/123**: every scenario (S1 Drift, S4 bank run, S7, S8, S9, S10 Floor), the negative tests, measured compute, and an account-substitution sweep of every instruction but the two read-only views (6,182 swaps refused, 10 Oct) |
| **Bounded proofs** <br><sub>Kani, and exhaustive checks</sub> | **15/15 harnesses verified** on 8 Oct (12 for every value of their types), 354 s. 6 exhaustive tests over ~584M inputs |
| **Differential** <br><sub>an independent Python reference vs the Rust core</sub> | **6,943,561 lines identical** (6 seeds × 200k cases, 27 Sep); 31 commands now, 300k cases on every pull request and 3M weekly in CI |
| **Programs on the real runtime** <br><sub>LiteSVM, mainnet feature set, mainnet token program</sub> | **133/133**: every scenario (S1 Drift, S4 bank run, S7, S8, S9, S10 Floor), the negative tests, measured compute, and an account-substitution sweep of every instruction but the two read-only views (6,182 swaps refused, 10 Oct) |
| **Bounded proofs** <br><sub>Kani, and exhaustive checks</sub> | **17/17 harnesses verified** on 14 Oct (14 for every value of their types), 227 s of verification ([`09 §5`](docs/09-VERIFICATION.md#5-bounded-proofs-kani-and-exhaustive-checks)). 6 exhaustive tests over ~584M inputs |
| **Differential** <br><sub>an independent Python reference vs the Rust core</sub> | **6,943,561 lines identical** (6 seeds × 200k cases, 27 Sep); 33 commands now, 300k cases on every pull request and 3M weekly in CI |
| **Program vs model** | Random steps on-chain, every outcome equal to the core's prediction: 12,000 (Vault), 300,000 with random limits and every brake (Vault), 200,000 (Floor) |
| **Mutation testing** <br><sub><code>cargo-mutants</code>, 669 injected bugs, in CI on every change to the core</sub> | **Every non-equivalent mutant killed**; 22 equivalent mutants, each with the reason it can't change behavior ([`09 §6`](docs/09-VERIFICATION.md#6-mutation-testing)) |
| **Coverage-guided fuzzing** <br><sub>libFuzzer, 8 targets: the byte parsers and the full-width limiter and ledger</sub> | 36M–277M executions per target in the 6 Oct run (10 min each), no program bug; every parser at full line coverage ([`09 §2`](docs/09-VERIFICATION.md#2-layers-and-current-results-10-oct-2026)) |
| **Coverage-guided fuzzing** <br><sub>libFuzzer, 9 targets: the byte parsers and the full-width limiter and ledger</sub> | 36M–277M executions per target in the 6 Oct run (10 min each), no program bug; every parser fuzzed in that run at full line coverage. That run had 8 targets: the guardian-set parser's, added 14 Oct, has no recorded 10-minute run or coverage measurement ([`09 §2`](docs/09-VERIFICATION.md#2-layers-and-current-results-10-oct-2026)) |
| **Property tests** <br><sub>G1–G5, fail closed, tightening, the SIMD-0500 gate, snapshot identity, ejection</sub> | 26/26, with coverage counters so a vacuous pass fails |
| **Golden vectors** <br><sub>every worked example in the docs, exact boundaries, the abort binaries' bytes, loader layouts</sub> | 119/119 identical, Rust = Python |
| **End to end** | [Above](#what-it-does-to-an-attack) |
Expand Down Expand Up @@ -226,6 +226,7 @@ programs/tests/ LiteSVM: scenarios, negative tests, compute, the program
cloud/ zero-dependency JavaScript: client, guardian bot, status page, end-to-end attack,
deployment and live-cluster checks
tools/floor_check.py read-only report on any upgradeable program
tools/claims.py the counts README and docs/ state, checked against the tree (scripts/check.sh)
reference/ independent Python reference, differential runner, golden vectors, fixtures, Drift model
evidence/ governance census (script + committed snapshot), model output
docs/ the full design (below)
Expand Down
2 changes: 1 addition & 1 deletion SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

| Component | State | Checked by |
|---|---|---|
| `bulkhead-core` (the math) | Built | An independent Python reference with a differential runner, golden vectors, property tests, exhaustive checks, 15 Kani harnesses, mutation testing (`docs/09-VERIFICATION.md`) |
| `bulkhead-core` (the math) | Built | An independent Python reference with a differential runner, golden vectors, property tests, exhaustive checks, 17 Kani harnesses, mutation testing (`docs/09-VERIFICATION.md`) |
| Programs: Floor, Vault, and Harbor (a demo protocol) | Built for sBPF v3 | LiteSVM on the real agave runtime and loader (scenarios, negative tests, compute), a program-vs-model differential, and an end-to-end run on a local validator |
| Bulkhead Cloud (guardian bot, status page, client) | Built | Unit tests, a JavaScript-vs-Python differential, the end-to-end run |
| Devnet deployment | Deployed 28 Sep 2026; upgraded in place 29 Sep, 6 Oct, 7 Oct, twice on 8 Oct, six times on 9 Oct, once on 10 Oct, once on 11 Oct and once on 15 Oct (below) | All three programs run the canonical build (Linux x86_64; CI publishes it) of `main` at PR #85 (Harbor unchanged since 6 Oct), matched byte for byte with the upgrade authority checked |
Expand Down
2 changes: 1 addition & 1 deletion docs/04-THREAT-MODEL.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ A security product with a bug is worse than no product. This file lists every ad
| I12 | No token leaves a vault except release, settle, lifeboat | program-vs-model differential (vault balance equals the model after every step) |
| I13 | Releases fail before the seal | program `nothing_can_be_released_before_the_seal…` |
| I14 | `vault.queued_amount == Σ pending tickets` | program-vs-model differential, after every step |
| I15 | Floor: no new binary before 72h unless a quorum approved that exact frozen buffer during a restore, or the snapshot is restored | 41 Floor tests on the real loader (`programs/tests/tests/floor.rs`) |
| I15 | Floor: no new binary before 72h unless a quorum approved that exact frozen buffer during a restore, or the snapshot is restored | 45 Floor tests on the real loader (`programs/tests/tests/floor.rs`) |
| I16 | Python reference and Rust core agree on every input | diff (6,943,561 identical lines in the final 6-seed run; 36 fixtures with expected outputs) |

## 4. The #1 risk: a bug in Bulkhead itself
Expand Down
2 changes: 1 addition & 1 deletion docs/05-PROGRAM-SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ Codes from 8000 (`error.rs`), disjoint from Floor (7000+), Anchor (6000+) and th

## 10. Compute (measured on the real runtime, through Harbor's CPI)

Measured 8 Oct 2026 by `compute_units_are_within_the_spec_targets` (`programs/tests/tests/vault.rs`), on a macOS (arm64) build of this tree. The canonical Linux build orders functions differently, so its figures can differ slightly.
Measured 8 Oct 2026 by `compute_units_are_within_the_spec_targets` (`programs/tests/tests/vault.rs`), on a macOS (arm64) build of that day's tree (#35, `25b5a87`); the Vault has changed since. Two figures are later and name their source: a first deposit's cost at a low bump (finding 75) and the full-ledger row (its own test, 14 Oct). The canonical Linux build orders functions differently, so its figures can differ slightly.

| Path | Compute units | Target |
|---|---|---|
Expand Down
Loading