Consensus Overview
Consensus is the part of NOOSChain that decides ordering: which accepted transactions become blocks, and in what order those blocks are committed.
It is not the part of the system that changes organizations, users, buckets, records, permissions, contracts, encrypted payload metadata, or state roots. Those changes happen later, during deterministic block execution.
This separation is one of the most important NOOSChain design rules:
Consensus orders work. Chain execution applies work.
What Consensus Does
Consensus backends provide an ordering layer for validators.
Depending on the backend, consensus may:
- Accept transaction hashes or block candidates.
- Elect or identify a leader.
- Replicate an ordered log.
- Commit a block or block DTO.
- Report committed work back to the TypeScript node.
Every runnable backend still commits the same NOOSChain block model. Once a block is committed, the normal chain executor applies it through the same domain handlers, permission checks, nonce rules, replay rules, and state-root pipeline.
What Consensus Does Not Do
Consensus code must not directly mutate domain state.
It does not directly create or edit:
- Organizations
- Users
- Nodes
- Buckets
- Bucket access rules
- Encrypted record metadata
- Smart-contract registry state
- Validator governance state
- Payload availability state
- State roots
Those changes are produced only by committed block execution. This makes replay and verification possible: a node can re-run the same blocks and reproduce the same canonical state.
Consensus And Deterministic Execution
A normal commit flow looks like this:
- An application, SDK, operator, or peer submits a signed transaction.
- The node validates the transaction enough to admit it to the local mempool.
- The configured consensus backend orders the transaction or a candidate block.
- A NOOSChain block is committed.
- The chain executor applies the block through deterministic domain handlers.
- State-root, replay, snapshot, and verification tools can check the result.
Permission failures are deterministic execution results. Consensus may order a transaction that later fails because the signer lacks a bucket permission. That failure is still canonical block execution and must be reproduced by replay under the block's protocol version.
Signature verification, logical-identity nonce consumption, bucket-key rotation, contract registry changes, and bucket permission checks all happen in deterministic execution. Consensus decides order; it does not authenticate users or mutate domain state directly.
Node Roles
Validators can admit transactions and participate in the configured consensus backend. Depending on the backend, they may propose, vote, replicate, or commit blocks.
Observers do not propose blocks or vote. They sync finalized blocks and execute them locally for read, audit, and verification workflows.
See Node Roles for the full role model.
Available Consensus Modes
The current runnable consensus paths are:
| Mode | Use It For | Notes |
|---|---|---|
| Single Node Consensus | Local development, isolated demos, simple single-instance deployments | One node builds blocks from its local mempool. No replication or quorum. |
| Raft With Noosraft | TypeScript multi-node development and integration clusters | In-process TypeScript Raft path. Crash-fault oriented, not BFT. |
| Raft With HashiCorp Raft | External-process Raft development/integration path | Go HashiCorp Raft sidecar owns Raft log and membership operations. Crash-fault oriented, not BFT. |
All three paths use the same deterministic execution, permission, nonce, replay, and state-root rules after a block is committed.
openbft is accepted as a future configuration stub. It is not implemented.
cometbft is reserved for a future Byzantine-fault-tolerant validator network. A future adapter should expose NOOSChain as an ABCI application or use a bridge process. CometBFT would own P2P, consensus, and finality; NOOSChain would remain the deterministic application and state machine.
Crash Faults And Byzantine Faults
The documented Raft paths are crash-fault-oriented. They are useful for local development, integration testing, and controlled deployments where the threat model matches Raft assumptions.
They are not Byzantine-fault-tolerant consensus systems. If your deployment requires tolerance of malicious validators, equivocation, or adversarial quorum behavior, treat the current Raft paths as insufficient and follow future BFT adapter work instead.
Transaction Gossip Is Not Consensus
Transaction gossip is a mempool propagation layer in front of consensus. It can help nodes share pending transactions and reject obviously invalid submissions early.
It does not consume nonces, commit blocks, or make canonical state changes. Consensus ordering and deterministic execution remain authoritative.
Validator Governance And Runtime Membership
Validator membership intent is consensus state. Protocol v1 includes validator governance transactions such as:
REGISTER_VALIDATOR_NODESUSPEND_VALIDATORREACTIVATE_VALIDATORRETIRE_VALIDATORUPDATE_VALIDATOR_ENDPOINTUPDATE_VALIDATOR_VOTING_POWER
These execute through protocol handlers and replay like any other transaction.
The active governance validator set is not automatically applied to every current runtime consensus backend.
HashiCorp Raft can apply explicit operator-approved runtime membership changes through reconciliation workflows. Noosraft still uses configured voters. Observability reports warnings when governance intent and runtime configuration diverge.
For operations, see:
For internals, see:
Conflict Handling
Finalized conflict handling is separate from consensus ordering. The current deterministic-finality policy treats same-height different-hash history as a critical incident, quarantines the peer, and refuses new sync/propose work until manual operator resolution.
Future Raft or BFT adapters may replace this policy with committed-log or quorum-certificate-specific conflict handling without changing domain execution.
Peer Scoring
Peer scoring is also outside consensus. It may quarantine or ban a transport peer locally for sync, gossip, and backfill defense.
Peer scoring must never change the validator set, voting power, finalized blocks, or protocol state. Validator suspension is handled by explicit validator-governance transactions.