# Quorum commit

> Decide if a round of votes commits a block. A validator commits only when enough others agree, and only once it holds the block itself.

Inspired by UOR-Foundation/malachite-usdc (https://github.com/UOR-Foundation/malachite-usdc). Benchmarks and a malachite patch showing BFT consensus that transmits content-addressed transaction references instead of the transactions. Pattern: Decision table, OMG DMN 1.5, hit policy FIRST. To write one of your own, follow How to build a decision table app (../../guides/decision-table/index.md). The prompt below is data, quoted from the example.

**Figure: What the Quorum commit app does.** A request goes in, the rules decide, and the Lean kernel has already proved what the rules promise.

| Step | What happens |
| --- | --- |
| 1. Request | precommits, quorum, timeout, payload |
| 2. 3 rules | the first that matches wins |
| 3. Answer | commit, wait, next, fetch |
| 4. Proved | 3 theorems, 38 tests |

Verified by prismpm verify in the pinned SDK. Fingerprint: 618f46c799f0ca9f1dda728cd8c806668f45983920f14a1759cfb2c09a0f600a. Acceptance vectors: 38. Claims: 6.

## The prompt

```json
{
  "schema": "prism/prompt/1",
  "goal": "Decide if a round of votes commits a block. A validator commits only when enough others agree, and only once it holds the block itself.",
  "pattern": "decisionTable",
  "repository": "UOR-Foundation/malachite-usdc",
  "license": "Apache-2.0",
  "app": {
    "name": "bft-commit",
    "title": "Quorum commit",
    "purpose": "Decide whether a round commits, waits, moves to the next round or fetches the block content, from the precommits seen, the quorum the validator set requires, whether the round timed out and whether the validator holds the referenced content.",
    "fields": [
      {
        "name": "precommits",
        "kind": "number",
        "min": 0,
        "means": "precommit votes seen, by voting power",
        "max": 1000
      },
      {
        "name": "quorum",
        "kind": "number",
        "min": 0,
        "means": "voting power a commit needs, more than two thirds",
        "max": 1000
      },
      {
        "name": "timeout",
        "kind": "choice",
        "values": [
          "no",
          "yes"
        ],
        "means": "whether the round's precommit timeout fired"
      },
      {
        "name": "payload",
        "kind": "choice",
        "values": [
          "held",
          "missing"
        ],
        "means": "whether the validator rebuilt the block from the referenced transactions"
      }
    ],
    "outcomes": [
      "commit",
      "wait",
      "next",
      "fetch"
    ],
    "meanings": {
      "commit": "the block is decided and finalized",
      "wait": "no quorum yet, the round continues",
      "next": "the round timed out without a quorum, the next round starts",
      "fetch": "a quorum decided a block whose content is missing: fetch it through the sync path, then commit"
    },
    "rules": [
      {
        "when": [
          {
            "field": "precommits",
            "op": ">=",
            "value": {
              "field": "quorum"
            }
          },
          {
            "field": "payload",
            "op": "is",
            "value": "missing"
          }
        ],
        "then": "fetch",
        "why": "implementation/README.md: anything missing is fetched through malachite's existing sync path, crates/sync"
      },
      {
        "when": [
          {
            "field": "precommits",
            "op": ">=",
            "value": {
              "field": "quorum"
            }
          }
        ],
        "then": "commit",
        "why": "docs/ARCHITECTURE.md: Tendermint-style rounds in malachite, more than two thirds of precommits decide the block"
      },
      {
        "when": [
          {
            "field": "timeout",
            "op": "is",
            "value": "yes"
          }
        ],
        "then": "next",
        "why": "docs/ARCHITECTURE.md section 2: propose, prevote and precommit rounds, a timeout without a quorum starts the next round"
      }
    ],
    "otherwise": "wait",
    "otherwiseWhy": "no quorum yet and time remains",
    "properties": [
      {
        "kind": "never",
        "when": [
          {
            "field": "precommits",
            "op": "<",
            "value": {
              "field": "quorum"
            }
          }
        ],
        "then": "commit",
        "why": "safety: no commit without a quorum"
      },
      {
        "kind": "never",
        "when": [
          {
            "field": "payload",
            "op": "is",
            "value": "missing"
          }
        ],
        "then": "commit",
        "why": "a block is committed only when its content can be rebuilt"
      },
      {
        "kind": "always",
        "when": [
          {
            "field": "precommits",
            "op": ">=",
            "value": {
              "field": "quorum"
            }
          },
          {
            "field": "payload",
            "op": "is",
            "value": "held"
          }
        ],
        "then": "commit",
        "why": "a quorum on held content always commits"
      }
    ],
    "examples": [
      {
        "request": "14 14 no held",
        "response": "commit"
      },
      {
        "request": "20 14 yes held",
        "response": "commit"
      },
      {
        "request": "14 14 no missing",
        "response": "fetch"
      },
      {
        "request": "13 14 yes held",
        "response": "next"
      },
      {
        "request": "13 14 yes missing",
        "response": "next"
      },
      {
        "request": "13 14 no held",
        "response": "wait"
      }
    ]
  },
  "stakeholders": [
    {
      "name": "Validator",
      "text": "Runs a validator and needs a block committed only on a quorum, and always on one when it holds the content.",
      "concerns": [
        "Proved guarantees",
        "Correct answers"
      ]
    },
    {
      "name": "Chain operator",
      "text": "Grows the validator set and needs consensus to carry references while content arrives off the critical path.",
      "concerns": [
        "Content before commit"
      ]
    }
  ],
  "concerns": [
    {
      "name": "Content before commit",
      "text": "A block proposed by reference is committed only once the validator holds its content, fetching anything missing through sync.",
      "model": "component"
    }
  ],
  "components": [
    {
      "name": "malachite",
      "text": "circlefin/malachite, the BFT consensus engine behind Arc that the repository's patch and benchmarks run against.",
      "kind": "externalSystem"
    },
    {
      "name": "malachite sync",
      "text": "malachite's crates/sync, the fetch fallback for content a validator does not hold.",
      "kind": "externalSystem"
    }
  ],
  "threats": [
    {
      "name": "Withheld payload",
      "text": "A proposer sends references but withholds the transactions, so validators commit a block they cannot execute.",
      "stride": "denialOfService",
      "asset": "answer",
      "likelihood": "medium",
      "impact": "major",
      "control": {
        "name": "Fetch before commit",
        "text": "A quorum on missing content is answered fetch, never commit, proved for every request.",
        "evidence": [
          {
            "kind": "proof",
            "reference": "BftCommitProofs::inv002Holds"
          },
          {
            "kind": "review",
            "reference": "implementation/README.md fetch-fallback"
          }
        ]
      }
    },
    {
      "name": "Reference to other bytes",
      "text": "A reference resolves to transactions other than those proposed.",
      "stride": "tampering",
      "asset": "request",
      "likelihood": "low",
      "impact": "critical",
      "accepted": "References are content addresses verified on receipt, BLAKE3 over canonical bytes per the UOR specification; the app sees only whether the content is held."
    },
    {
      "name": "Equivocating validators",
      "text": "A third or more of the voting power signs conflicting precommits.",
      "stride": "repudiation",
      "asset": "request",
      "likelihood": "low",
      "impact": "critical",
      "accepted": "BFT safety assumes less than a third of the voting power is faulty; the app counts the precommits it is given against the quorum."
    }
  ],
  "quality": [
    {
      "characteristic": "Reliability",
      "subcharacteristic": "Fault tolerance",
      "requirement": "Commit only on a quorum",
      "text": "No round commits with precommits below the quorum, whatever the timeout or content.",
      "measure": "Commits without a quorum",
      "measureText": "Requests with precommits below quorum answered commit.",
      "threshold": 0
    }
  ],
  "journeys": [
    {
      "stakeholder": "Validator",
      "steps": [
        "REQ-002",
        "REQ-003",
        "otherwise",
        "INV-001"
      ]
    },
    {
      "stakeholder": "Chain operator",
      "steps": [
        "REQ-001",
        "INV-002",
        "INV-003"
      ]
    }
  ],
  "axioms": {
    "inv002Holds": [
      "Classical.choice",
      "Quot.sound",
      "propext"
    ]
  }
}
```

## Claims

- BC-01: The app never answers commit when precommits is below quorum
- BC-02: The app never answers commit when payload is missing
- BC-03: The app always answers commit when precommits is at least quorum and payload is held
- BC-04: The architecture description declares every stakeholder, concern, component, edge, viewpoint and view it references
- BC-05: The ISO/IEC 25010 quality model numbers every characteristic, subcharacteristic, requirement and measure, and every parent it names is declared
- BC-06: Every compliance obligation is numbered in order and names its evidence

## Pattern

Decision table: OMG DMN 1.5, hit policy FIRST. The rules are tried in order, and the first one that matches gives the answer. If none matches, the default answer applies. This is a DMN decision table with the FIRST hit policy.

| Pattern | Standard | Answers |
| --- | --- | --- |
| Decision table | OMG DMN 1.5, hit policy FIRST | commit, wait, next, fetch |

**Figure: Rules for each answer.** Each bar counts the rules that give one answer. When no rule matches, the answer is wait.

|  | rules |
| --- | --- |
| commit | 1 |
| wait | 0 |
| next | 1 |
| fetch | 1 |

## Behavior

A request is precommits, quorum, timeout, payload, separated by spaces. The first rule that matches decides. If none matches, the answer is wait. A request over 112 bytes, or in any other form, is answered invalid.

| Rule | When | Answer | Why |
| --- | --- | --- | --- |
| REQ-001 | precommits is at least quorum and payload is missing | fetch | implementation/README.md: anything missing is fetched through malachite's existing sync path, crates/sync |
| REQ-002 | precommits is at least quorum | commit | docs/ARCHITECTURE.md: Tendermint-style rounds in malachite, more than two thirds of precommits decide the block |
| REQ-003 | timeout is yes | next | docs/ARCHITECTURE.md section 2: propose, prevote and precommit rounds, a timeout without a quorum starts the next round |
| otherwise | no rule matches | wait | no quorum yet and time remains |

## Properties Lean proves

Each property is a theorem about the same definitions the app is built from. It is proved for every request, not only the tested ones.

| Property | Statement | Theorem | Why |
| --- | --- | --- | --- |
| INV-001 | It never answers commit when precommits is below quorum. | BftCommitProofs::inv001Holds | safety: no commit without a quorum |
| INV-002 | It never answers commit when payload is missing. | BftCommitProofs::inv002Holds | a block is committed only when its content can be rebuilt |
| INV-003 | It always answers commit when precommits is at least quorum and payload is held. | BftCommitProofs::inv003Holds | a quorum on held content always commits |

## Architecture

Stakeholders and the concerns each one views the app through (ISO/IEC/IEEE 42010).

| Stakeholder | Who they are | Concerns |
| --- | --- | --- |
| Chain operator | Grows the validator set and needs consensus to carry references while content arrives off the critical path. | Content before commit |
| Validator | Runs a validator and needs a block committed only on a quorum, and always on one when it holds the content. | Proved guarantees, Correct answers |
| Verifier | Anyone who loads the holo, checks its fingerprint and replays its acceptance vectors before trusting an answer. | Integrity of the published app, Refused malformed requests, Proved guarantees |

## Concerns

What the stakeholders care about, and the model each is viewed in.

| Concern | What it means | Model |
| --- | --- | --- |
| Content before commit | A block proposed by reference is committed only once the validator holds its content, fetching anything missing through sync. | component |
| Correct answers | Every well-formed request is answered by the first rule that matches it, or wait when none does, as the spec states. | quality |
| Integrity of the published app | What a visitor runs is the holo the build verified, with its fingerprint and signed provenance beside it. | security |
| Proved guarantees | Each of the 3 properties of the spec holds for every request, proved by the Lean kernel. | quality |
| Refused malformed requests | A request that is not the 4 fields in order, or is longer than 112 bytes, is answered invalid and never guessed. | security |

## Components

8 components and 11 edges between them.

| Component | Kind | What it is |
| --- | --- | --- |
| Browser | externalSystem | The visitor's web browser, which loads the page and runs the Quorum commit guest. |
| GitHub Pages | externalSystem | Serves the page and the holo from the repository Pages workflow. |
| malachite | externalSystem | circlefin/malachite, the BFT consensus engine behind Arc that the repository's patch and benchmarks run against. |
| malachite sync | externalSystem | malachite's crates/sync, the fetch fallback for content a validator does not hold. |
| Prism build | cliAdapter | prismpm verify in the SDK image prismpm.lock pins: it checks every theorem, builds the guest and replays every vector. |
| Quorum commit guest | service | The Core-Wasm guest built from the model: it answers one request of at most 112 bytes with one answer of at most 64. |
| Quorum commit page | staticSite | The page the template publishes: the holo, its fingerprint, its provenance and its acceptance vectors. |
| Source repository | externalSystem | The repository that holds the prompt, the model and its gate. |

## Design views

The SDK checks each view against the system model and draws it as OPL and PlantUML.

| View | Diagram | Viewpoint |
| --- | --- | --- |
| Deciding a Quorum commit request | opmObjectProcess | Validator: Correct answers |
| Components of Quorum commit | umlComponent | Verifier: Integrity of the published app |
| Answering a Quorum commit request | umlSequence | Validator: Correct answers |
| States of the Quorum commit guest | umlStateMachine | Verifier: Refused malformed requests |

## Features and journeys

8 features. Each names the definitions that do the work and the tests that accept it. Each stakeholder has one journey.

| Feature | Calls | Accepted by |
| --- | --- | --- |
| When precommits is at least quorum and payload is missing, the answer is fetch. | BftCommit::rule1, BftCommit::judge | BftCommit::application |
| When precommits is at least quorum, the answer is commit. | BftCommit::rule2, BftCommit::judge | BftCommit::application |
| When timeout is yes, the answer is next. | BftCommit::rule3, BftCommit::judge | BftCommit::application |
| When no rule matches, the answer is wait. | BftCommit::judge | BftCommit::application |
| A request that is not precommits, quorum, timeout, payload in order, separated by single spaces, or is over 112 bytes, is answered invalid. | BftCommit::dispatch, BftCommit::decodeField1 | BftCommit::application |
| It never answers commit when precommits is below quorum. | BftCommit::judge | BftCommitProofs::inv001Holds |
| It never answers commit when payload is missing. | BftCommit::judge | BftCommitProofs::inv002Holds |
| It always answers commit when precommits is at least quorum and payload is held. | BftCommit::judge | BftCommitProofs::inv003Holds |

## Journeys

The ordered features each stakeholder takes.

| Stakeholder | Steps |
| --- | --- |
| Chain operator | REQ-001 → INV-002 → INV-003 |
| Validator | REQ-002 → REQ-003 → otherwise → INV-001 |
| Verifier | refuse → INV-001 → INV-002 → INV-003 |

## Security and threat model

12 threats against 4 assets. Each has a STRIDE category, and either a control with evidence or a risk that is accepted on purpose.

| Threat | STRIDE | Asset | Risk | Answered by |
| --- | --- | --- | --- | --- |
| Answer that breaks INV-001 | repudiation | Answer | medium likelihood, critical impact | Proof of INV-001: proof BftCommitProofs::inv001Holds |
| Answer that breaks INV-002 | repudiation | Answer | medium likelihood, critical impact | Proof of INV-002: proof BftCommitProofs::inv002Holds |
| Answer that breaks INV-003 | repudiation | Answer | medium likelihood, critical impact | Proof of INV-003: proof BftCommitProofs::inv003Holds |
| Equivocating validators | repudiation | Request bytes | low likelihood, critical impact | accepted: BFT safety assumes less than a third of the voting power is faulty; the app counts the precommits it is given against the quorum. |
| Granted capability | informationDisclosure | Answer | low likelihood, major impact | No capability granted: gate prism-code check refuses an ungranted guest import |
| Malformed request | tampering | Request bytes | high likelihood, major impact | Strict decoder: gate malformed-request acceptance vectors, replayed in the compiled guest by prismpm verify |
| Oversized request | denialOfService | Request bytes | medium likelihood, minor impact | Bounded request: gate acceptance vectors at the request bound, one byte over it, and at the guest allocation bound, replayed by prismpm verify |
| Reference to other bytes | tampering | Request bytes | low likelihood, critical impact | accepted: References are content addresses verified on receipt, BLAKE3 over canonical bytes per the UOR specification; the app sees only whether the content is held. |
| Substituted holo | spoofing | Published holo | low likelihood, critical impact | Fingerprint and provenance: gate actions/attest-build-provenance in the pages workflow; gate prism-code check of the holo identities in the page |
| Substituted host | spoofing | Published holo | low likelihood, critical impact | accepted: A page cannot defend against its own host. The holo carries signed build provenance a visitor can check, and the app can be rebuilt from its prompt. |
| Tampered model | tampering | Model source | low likelihood, major impact | Regenerated from the prompt: gate prismpm verify in the SDK image prismpm.lock pins; review app/prompt.json |
| Withheld payload | denialOfService | Answer | medium likelihood, major impact | Fetch before commit: proof BftCommitProofs::inv002Holds; review implementation/README.md fetch-fallback |

## Quality

ISO/IEC 25010:2023 requirements. Each has a measure and a threshold that a theorem pins.

| Requirement | Characteristic | Measure | Threshold |
| --- | --- | --- | --- |
| Bounded allocation: The guest allocates at most 224 bytes for one request. | Performance efficiency: Resource utilization | Guest allocation bytes | 224 |
| Bounded request: A request over 112 bytes is refused before any field is read. | Performance efficiency: Time behaviour | Request bytes read | 112 |
| Commit only on a quorum: No round commits with precommits below the quorum, whatever the timeout or content. | Reliability: Fault tolerance | Commits without a quorum | 0 |
| Every property proved: All 3 properties are theorems the Lean kernel checks. | Security: Integrity | Unproved properties | 0 |
| Every request answered: Every request gets an answer: a rule, wait otherwise, or invalid. | Functional suitability: Functional completeness | Unanswered requests | 0 |
| Every vector replays: All 38 acceptance vectors replay in the compiled guest, the shortest 0 bytes long. | Reliability: Faultlessness | Failed vectors | 0 |
| Examples answered as stated: Every one of the 6 examples of the spec is answered as it states. | Functional suitability: Functional correctness | Example mismatches | 0 |

## Compliance

One obligation per standard, each naming its evidence.

| Standard | Subject | Evidence |
| --- | --- | --- |
| ISO/IEC/IEEE 42010:2022 | Architecture description | Architecture::architectureDescriptionHolds |
| ISO/PAS 19450:2015 and OMG UML 2.5.1 | Design views | Design::viewOpmDecide, Design::viewUmlComponents, Design::viewUmlRequest, Design::viewUmlStates |
| ISO/IEC 25010:2023 | Product quality | Quality::qualityModelHolds |
| ISO/IEC 27034-1:2011 and ISO/IEC 27005:2022 | Application security and risk | Security::controlSet |
| OMG DMN 1.5, hit policy FIRST | Decision table | BftCommit::judge |
| OpenSpec | Requirements | BftCommit::application |
| SPDX Apache-2.0 | Licensing | BftCommit::application |

## Rendered design views

Written by the SDK from the design records when it verified the app.

### design/Design.viewOpmDecide.opl

```
View: Design::viewOpmDecide
Title: Deciding a Quorum commit request
Viewpoint: Architecture::viewpointValidatorCorrectAnswers
Notation: ISO/PAS 19450:2015 OPM, Prism OPL profile

componentBrowser is an object.
componentQuorumCommitGuest is an object.
componentQuorumCommitGuest can be stateDeciding or stateIdle.
processDecide is a process.
processEncodeAnswer is a process.
processJudge is a process.
processParseRequest is a process.
componentQuorumCommitGuest handles processDecide.
processParseRequest requires componentBrowser.
processEncodeAnswer affects componentBrowser.
processJudge invokes processEncodeAnswer.
processParseRequest invokes processJudge.
processDecide zooms into processParseRequest, processJudge, and processEncodeAnswer, in that sequence.

```

### design/Design.viewUmlComponents.puml

```
@startuml
' UML 2.5.1 component diagram
' view: Design::viewUmlComponents
' viewpoint: Architecture::viewpointVerifierIntegrityOfThePublishedApp
title Components of Quorum commit
component "componentBrowser" as c0
component "componentGitHubPages" as c1
component "componentMalachite" as c2
component "componentMalachiteSync" as c3
component "componentPrismBuild" as c4
component "componentQuorumCommitGuest" as c5
component "componentQuorumCommitPage" as c6
component "componentSourceRepository" as c7
c0 --> c5 : edgeBrowserToQuorumCommitGuest
c1 --> c0 : edgeGitHubPagesToBrowser
c3 --> c5 : edgeMalachiteSyncToQuorumCommitGuest
c2 --> c5 : edgeMalachiteToQuorumCommitGuest
c4 --> c5 : edgePrismBuildToQuorumCommitGuest
c4 --> c6 : edgePrismBuildToQuorumCommitPage
c5 --> c0 : edgeQuorumCommitGuestToBrowser
c5 --> c2 : edgeQuorumCommitGuestToMalachite
c5 --> c3 : edgeQuorumCommitGuestToMalachiteSync
c6 --> c1 : edgeQuorumCommitPageToGitHubPages
c7 --> c4 : edgeSourceRepositoryToPrismBuild
@enduml

```

### design/Design.viewUmlRequest.puml

```
@startuml
' UML 2.5.1 sequence diagram
' view: Design::viewUmlRequest
' viewpoint: Architecture::viewpointValidatorCorrectAnswers
title Answering a Quorum commit request
participant "componentBrowser" as p0
participant "componentQuorumCommitGuest" as p1
p0 -> p1 : processDecide
p1 --> p0 : processDecide
@enduml

```

### design/Design.viewUmlStates.puml

```
@startuml
' UML 2.5.1 state machine diagram
' view: Design::viewUmlStates
' viewpoint: Architecture::viewpointVerifierRefusedMalformedRequests
title States of the Quorum commit guest
state "stateAnsweredCommit" as s0
state "stateAnsweredFetch" as s1
state "stateAnsweredNext" as s2
state "stateAnsweredWait" as s3
state "stateDeciding" as s4
state "stateIdle" as s5
state "stateRefused" as s6
[*] --> s5
s5 --> s4 : processParseRequest
s5 --> s6 : processParseRequest
s4 --> s1 : processRule1
s4 --> s0 : processRule2
s4 --> s2 : processRule3
s4 --> s3 : processOtherwise
s0 --> s5 : processEncodeAnswer
s3 --> s5 : processEncodeAnswer
s2 --> s5 : processEncodeAnswer
s1 --> s5 : processEncodeAnswer
s6 --> s5 : processEncodeAnswer
@enduml

```

## Prism source

Every file the builder wrote, laid out as a repository created from UOR-Foundation/template; the download prism-bft-commit.zip has them all.

- app/src/Architecture.lex.tex (399 lines)
- app/src/Compliance.lex.tex (56 lines)
- app/src/Design.lex.tex (556 lines)
- app/src/Features.lex.tex (94 lines)
- app/src/Quality.lex.tex (354 lines)
- app/src/Security.lex.tex (537 lines)
- app/src/BftCommit.lex.tex (227 lines)
- app/src/BftCommitProofs.lex.tex (102 lines)
- app/lexlean.toml (43 lines)
- app/prompt.json (293 lines)
- model/ids.toml (59 lines)
- features/suites/bft\_commit.feature (38 lines)
- crates/conformance/tests/bft\_commit.rs (122 lines)
- site/app.json (103 lines)
- openspec/specs/bft-commit/spec.md (149 lines)
