Docs Fault Lab
Fault Lab runs
How a Fault Lab run works. A twelve-validator sandbox, one scenario's fault in one window, every event recorded, and the evidence the run must end in.
The Fault Lab runs the attacks New Constellation is built against, on a sandbox cluster, and answers each with evidence read from the cluster's own records. Each scenario puts one fault into one window and ends in the evidence its lemma predicts; a run without that evidence ends failed.
| Scenario | The attack | The evidence | Shows |
|---|---|---|---|
| Last look | a proposer delays its commitment to see the others first | late_block_dropped, skip_certificate | Lemma 2.3, proposal hiding |
| Censorship | two proposers drop a transaction the third carries | transaction_included | Lemma 2.2, selective-censorship resistance |
| Crash | a proposer is silent from the window's start | two_proposers_continue | Theorem 2.1, NewCon correctness |
| Equivocation | a proposer signs two commitments for one slot | slashing_proof, skip_certificate | Lemma 2.4, accountable equivocation |
| Split commitments | a commitment goes to one co-proposer only | skip_certificate | Lemma 2.2, selective-censorship resistance |
| Private front-run | a proposer tries to read a 2-of-3 transaction early | unreadable_fragment | Section 3.2 and Lemma 2.3 |
The sandbox
Every run starts a fresh cluster like acrux net up: twelve validators in FRA, NYC and TYO, four per hub, from the same genesis, for 12 seconds. The run's seed sets the schedule, so a seed replays the same windows and proposers.
The fault goes into the fifth window, window 4, slots 64 to 79, once the net has settled. The attacker is that window's proposer 3; in Private front-run it is receiver 1, and in Censorship proposer 3 is the honest one. Everything else in the run is the protocol as Acrux Net runs it.
Starting a run
/lab: pick a scenario and run it; the run opens at /lab/<run> and streams as it happenscurl -X POST http://127.0.0.1:4920/v1/lab/runs \
-H 'content-type: application/json' \
-d '{ "scenario": "last-look" }'acrux lab run --scenario last-look --seed demo --out runs/last-lookThe API answers 201 with the run in status queued, then running, then done, or failed_to_start (POST /v1/lab/runs). The CLI options are on CLI.
What a run records
Events. Every protocol event of the window before the fault, the faulty window and the window after it, slots 48 to 95, in the event stream's envelope: the slices, commitments and their arrivals, attestations, the agreed set or the skip, the merge, execution, votes and certificates. The CLI writes them to events.jsonl, one per line. The API serves them at GET /v1/lab/runs/{id}/events and live at /stream.
Evidence. Each piece of evidence is a lab.evidence event and an entry in the run's evidence: its kind, slot and proposer, the transaction, hashes and signatures it rests on, and a sentence saying what it shows (Evidence).
Outcome. When the run ends, outcome.json holds:
| Field | Meaning |
|---|---|
status | done when every expected kind of evidence was recorded; failed otherwise |
outcome | the evidence's sentences, joined |
evidence | each piece of evidence |
failure | for a failed run, the expected evidence that is missing |
Evidence kinds
kind | Recorded when |
|---|---|
late_block_dropped | a proposer's commitment arrived after the 2δlocal window and its co-proposers attested it as late |
transaction_included | the marked transaction executed, carried only by the honest proposer |
two_proposers_continue | the window's first slot agreed on P = {1, 2} without the silent proposer |
slashing_proof | two commitments for one slot carry the same proposer's signature |
skip_certificate | a cblock of the faulty window was skip-certified |
unreadable_fragment | the attacking receiver holds fewer fragments than t |
The six pages that follow each show the evidence of a recorded run on the twelve validators.