Raft With HashiCorp Raft

RAFT_ENGINE=hashicorp-go runs NOOSChain's Raft ordering through an external Go sidecar built on HashiCorp Raft. The TypeScript node still owns transactions, block construction, deterministic execution, state roots, snapshots, replay, permissions, and encryption. The sidecar owns Raft leader election, log replication, sidecar persistence, and runtime membership operations.

Use it when you want the current external-process Raft path.

Configuration

NOOS_CONSENSUS_MODE=raft
RAFT_ENGINE=hashicorp-go
HASHICORP_GO_RAFT_BINARY_PATH=external/raft-go/bin/hashicorp-raft
HASHICORP_GO_RAFT_NODE_ID=node-a
HASHICORP_GO_RAFT_CLUSTER_ID=noos-dev-go-raft
HASHICORP_GO_RAFT_HTTP_BIND=http://127.0.0.1:9001
HASHICORP_GO_RAFT_BIND=127.0.0.1:10001
HASHICORP_GO_RAFT_DATA_DIR=.noos-raft-go/node-a
HASHICORP_GO_RAFT_CALLBACK_BASE=http://127.0.0.1:7001
HASHICORP_GO_RAFT_BOOTSTRAP=true
HASHICORP_GO_RAFT_PEERS=[{"nodeId":"node-b","httpUrl":"http://127.0.0.1:9002","raftAddress":"127.0.0.1:10002","callbackBaseUrl":"http://127.0.0.1:7002"}]

Build the sidecar before running this mode:

npm run build:raft-go

Behavior

The sidecar receives opaque NOOSChain block DTOs. It does not receive raw database mutations and does not execute domain logic.

The normal flow is:

1. TypeScript builds and simulates a candidate NOOSChain block.
2. TypeScript submits the block DTO to the sidecar proposal API.
3. HashiCorp Raft replicates and commits the opaque entry.
4. The sidecar calls back into TypeScript with the committed entry.
5. TypeScript applies the block through deterministic NOOSChain execution.
6. TypeScript verifies the block hash and state root.

If a committed callback is missed, the TypeScript engine can fetch committed log entries from the sidecar and replay them through the same commit path.

Runtime Membership

HashiCorp Raft can apply explicit operator-approved runtime membership changes. Governance transactions still define the intended validator set in consensus state, but they do not automatically mutate runtime voters.

The operator workflow is:

1. Commit governance changes.
2. Inspect the runtime membership reconciliation plan.
3. Approve specific operations.
4. Execute the plan through protected operator APIs or CLI commands.
5. Verify consensus, replay, and node health.

The sidecar can add voters, add non-voters, and remove voters through the HashiCorp Raft membership API. NOOSChain sequences those operations cautiously and stops on unsafe or failed states.

Network Surfaces

HashiCorp Raft mode has three network surfaces:

• NOOSChain TypeScript HTTP APIs, controlled by NOOS_TLS_*.
• Sidecar HTTP control and callback APIs, controlled by GO_RAFT_TLS_*.
• HashiCorp Raft TCP replication, controlled by GO_RAFT_TCP_TLS_*.

See TLS/mTLS for the transport security model.

Limitations

• Development/integration bridge only.
• No Byzantine-fault tolerance.
• Runtime membership is explicit operator action, not automatic governance application.
• NOOSChain snapshot/checkpoint integration with HashiCorp InstallSnapshot is still future work.

Detailed implementation and deployment notes are in:

• HashiCorp Raft Engine Bridge
• HashiCorp Raft Deployment

Useful Checks

npm run build:raft-go
npm run test:raft:go
npm run test:raft:go:tcp-tls
npm run test:raft:membership
npm run stability:go-raft-chaos